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: 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
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:
              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'
            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'
  /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:
              oneOf:
                - title: New Individual Customer
                  allOf:
                    - $ref: '#/components/schemas/IndividualCustomerUpdate'
                    - type: object
                      required:
                        - platformCustomerId
                      properties:
                        platformCustomerId:
                          type: string
                          description: Platform-specific customer identifier
                          example: 9f84e0c2a72c4fa
                        kycUrl:
                          type: string
                          description: A KYC URL to be shared with your individual customer if KYC needs to be completed
                          example: https://example.com/kyc
                - title: New Business Customer
                  allOf:
                    - $ref: '#/components/schemas/BusinessCustomerUpdate'
                    - type: object
                      required:
                        - platformCustomerId
                        - businessInfo
                      properties:
                        platformCustomerId:
                          type: string
                          description: Platform-specific customer identifier
                          example: 9f84e0c2a72c4fa
                        kycUrl:
                          type: string
                          description: A KYC URL to be shared with your business customer if KYC needs to be completed
                          example: https://example.com/kyc
                        businessInfo:
                          type: object
                          required:
                            - legalName
                          properties:
                            legalName:
                              type: string
                              description: Legal name of the business
                              example: Acme Corporation, Inc.
                            registrationNumber:
                              type: string
                              description: Business registration number
                              example: BRN-123456789
                            taxId:
                              type: string
                              description: Tax identification number
                              example: EIN-987654321
            examples:
              individualCustomerWithUmaAddress:
                summary: Create individual customer with UMA address, including deposit bank account information.
                value:
                  umaAddress: $jane.doe@uma.domain.com
                  platformCustomerId: 7b3c5a89d2f1e0
                  customerType: INDIVIDUAL
                  fullName: Jane Doe
                  birthDate: '1992-03-25'
                  address:
                    line1: 123 Pine Street
                    line2: Unit 501
                    city: Seattle
                    state: WA
                    postalCode: '98101'
                    country: US
              individualCustomerWithoutUmaAddress:
                summary: Create individual customer without UMA address (will be generated)
                value:
                  platformCustomerId: 7b3c5a89d2f1e0
                  customerType: INDIVIDUAL
                  fullName: John Smith
                  birthDate: '1985-06-10'
                  address:
                    line1: 456 Oak Avenue
                    city: Portland
                    state: OR
                    postalCode: '97201'
                    country: US
              businessCustomer:
                summary: Create business customer example
                value:
                  platformCustomerId: 6e4d2c0b8a9f3
                  customerType: BUSINESS
                  businessInfo:
                    legalName: Acme Corporation
                    registrationNumber: BRN-456789123
                    taxId: EIN-987123456
                  address:
                    line1: 400 Commerce Way
                    city: Austin
                    state: TX
                    postalCode: '78701'
                    country: US
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - title: Individual Customer
                    $ref: '#/components/schemas/IndividualCustomer'
                  - title: Business Customer
                    $ref: '#/components/schemas/BusinessCustomer'
                discriminator:
                  propertyName: customerType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualCustomer'
                    BUSINESS: '#/components/schemas/BusinessCustomer'
        '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:
                      oneOf:
                        - title: Individual Customer
                          $ref: '#/components/schemas/IndividualCustomer'
                        - title: Business Customer
                          $ref: '#/components/schemas/BusinessCustomer'
                      discriminator:
                        propertyName: customerType
                        mapping:
                          INDIVIDUAL: '#/components/schemas/IndividualCustomer'
                          BUSINESS: '#/components/schemas/BusinessCustomer'
                  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:
                oneOf:
                  - title: Individual Customer
                    $ref: '#/components/schemas/IndividualCustomer'
                  - title: Business Customer
                    $ref: '#/components/schemas/BusinessCustomer'
                discriminator:
                  propertyName: customerType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualCustomer'
                    BUSINESS: '#/components/schemas/BusinessCustomer'
        '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:
              oneOf:
                - title: Update Individual Customer
                  $ref: '#/components/schemas/IndividualCustomerUpdate'
                - title: Update Business Customer
                  $ref: '#/components/schemas/BusinessCustomerUpdate'
              discriminator:
                propertyName: customerType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualCustomerUpdate'
                  BUSINESS: '#/components/schemas/BusinessCustomerUpdate'
            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:
                oneOf:
                  - title: Individual Customer
                    $ref: '#/components/schemas/IndividualCustomer'
                  - title: Business Customer
                    $ref: '#/components/schemas/BusinessCustomer'
                discriminator:
                  propertyName: customerType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualCustomer'
                    BUSINESS: '#/components/schemas/BusinessCustomer'
        '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:
                oneOf:
                  - title: Individual Customer
                    $ref: '#/components/schemas/IndividualCustomer'
                  - title: Business Customer
                    $ref: '#/components/schemas/BusinessCustomer'
                discriminator:
                  propertyName: customerType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualCustomer'
                    BUSINESS: '#/components/schemas/BusinessCustomer'
        '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/Error'
        '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:
        - Customers
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                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
        '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.

        **Sandbox Testing:** In sandbox mode, use these account number patterns to test different transfer scenarios. These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing. For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are:
        - Account numbers ending in **002**: Insufficient funds (transfer-in will fail)
        - Account numbers ending in **003**: Account closed/invalid (transfers will fail)
        - Account numbers ending in **004**: Transfer rejected (bank rejects the transfer)
        - Account numbers ending in **005**: Timeout/delayed failure (stays pending ~30s, then fails)
        - Any other account number: Success (transfers complete normally)
      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: US_ACCOUNT
                    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:
                  - accounts
                properties:
                  accounts:
                    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.

        **Sandbox Testing:** In sandbox mode, use these account number patterns to test different transfer scenarios. These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing. For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are:
        - Account numbers ending in **002**: Insufficient funds (transfer-in will fail)
        - Account numbers ending in **003**: Account closed/invalid (transfers will fail)
        - Account numbers ending in **004**: Transfer rejected (bank rejects the transfer)
        - Account numbers ending in **005**: Timeout/delayed failure (stays pending ~30s, then fails)
        - Any other account number: Success (transfers complete normally)
      operationId: createPlatformExternalAccount
      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:
                  currency: USD
                  accountInfo:
                    accountType: US_ACCOUNT
                    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'
  /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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source
                - destination
              properties:
                source:
                  type: object
                  required:
                    - accountId
                  properties:
                    accountId:
                      type: string
                      description: Reference to an external account ID
                      example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  description: Source external account details
                destination:
                  type: object
                  required:
                    - accountId
                  properties:
                    accountId:
                      type: string
                      description: Reference to an internal account ID
                      example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  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
            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/Transaction'
        '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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source
                - destination
              properties:
                source:
                  type: object
                  required:
                    - accountId
                  properties:
                    accountId:
                      type: string
                      description: Reference to an internal account ID
                      example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  description: Source internal account details
                destination:
                  type: object
                  required:
                    - accountId
                  properties:
                    accountId:
                      type: string
                      description: Reference to an external account ID
                      example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  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
            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/Transaction'
        '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 a 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.

        **Sandbox Testing:** When using the `externalAccountDetails` destination type in sandbox mode, use account number patterns ending in specific digits to test different scenarios.
        These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing.
        For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are:
        - Account numbers ending in **002**: Insufficient funds (transfer-in will fail)
        - Account numbers ending in **003**: Account closed/invalid (transfers will fail)
        - Account numbers ending in **004**: Transfer rejected (bank rejects the transfer)
        - Account numbers ending in **005**: Timeout/delayed failure (stays pending ~30s, then fails)
        - Any other account number: Success (transfers complete normally)
      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:
                    accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                    currency: EUR
                  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:
                    accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    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:
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000009
                    currency: USD
                  destination:
                    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'
        '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/Transaction'
                  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/Transaction'
        '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:
              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`.
      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:
              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
      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'
  /webhooks/test:
    post:
      summary: Send a test webhook
      description: Send a test webhook to the configured endpoint
      operationId: sendTestWebhook
      tags:
        - Webhooks
      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:
                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
        '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 from a given platform customer.
      description: |
        Create an UMA invitation from a given platform customer.
      operationId: createInvitation
      tags:
        - Invitations
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              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'
      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 a specific UMA invitation by code.
      description: |
        Get a specific UMA invitation by 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:
              type: object
              required:
                - inviteeUma
              properties:
                inviteeUma:
                  type: string
                  description: The UMA address of the customer claiming the invitation
                  example: $invitee@uma.domain
      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:
              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
      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:
              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
      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:
              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
            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: This endpoint provides a list of Counterparty Providers that are available.
      description: |
        This endpoint provides a list of Counterparty Providers that are available.

        The response includes basic information about each provider, such as its UMA address, name, and supported currencies.
        This can be used to determine which providers are available for sending or receiving payments.
      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:
              type: object
              title: tokenCreate
              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'
              required:
                - name
                - permissions
      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:
                  transaction:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: PENDING
                    type: INCOMING
                    senderUmaAddress: $sender@external.domain
                    receiverUmaAddress: $recipient@uma.domain
                    receivedAmount:
                      amount: 50000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    reconciliationInstructions:
                      reference: REF-123456789
                    counterpartyInformation:
                      FULL_NAME: John Sender
                      BIRTH_DATE: '1985-06-15'
                      NATIONALITY: US
                  requestedReceiverCustomerInfoFields:
                    - name: NATIONALITY
                      mandatory: true
                    - name: ADDRESS
                      mandatory: false
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: INCOMING_PAYMENT
              incomingCompletedPayment:
                summary: Completed payment notification
                value:
                  transaction:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: COMPLETED
                    type: INCOMING
                    senderUmaAddress: $sender@external.domain
                    receiverUmaAddress: $recipient@uma.domain
                    receivedAmount:
                      amount: 50000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    settledAt: '2025-08-15T14:30:00Z'
                    createdAt: '2025-08-15T14:25:18Z'
                    description: Payment for services
                    reconciliationInstructions:
                      reference: REF-123456789
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: INCOMING_PAYMENT
      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 webhookId)
          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 or fails.
      operationId: outgoingPaymentWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutgoingPaymentWebhook'
            examples:
              outgoingCompletedPayment:
                summary: Completed outgoing payment
                value:
                  transaction:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: COMPLETED
                    type: OUTGOING
                    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
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    settlementTime: '2025-08-15T14:30:00Z'
                    createdAt: '2025-08-15T14:25:18Z'
                    description: 'Payment for invoice #1234'
                    exchangeRate: 0.92
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    paymentInstructions:
                      - accountOrWalletInfo:
                          reference: UMA-Q12345-REF
                          accountType: US_ACCOUNT
                          accountNumber: 987654321
                          routingNumber: 123456789
                          accountCategory: CHECKING
                          bankName: Chase Bank
                      - accountOrWalletInfo:
                          accountType: SOLANA_WALLET
                          assetType: USDC
                          address: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: OUTGOING_PAYMENT
              failedPayment:
                summary: Failed outgoing payment
                value:
                  transaction:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: FAILED
                    type: OUTGOING
                    senderUmaAddress: $sender@uma.domain
                    receiverUmaAddress: $recipient@external.domain
                    sentAmount:
                      amount: 10550
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    createdAt: '2025-08-15T14:25:18Z'
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    paymentInstructions:
                      - accountOrWalletInfo:
                          reference: UMA-Q12345-REF
                          accountType: US_ACCOUNT
                          accountNumber: 987654321
                          routingNumber: 123456789
                          accountCategory: CHECKING
                          bankName: Chase Bank
                      - accountOrWalletInfo:
                          accountType: SOLANA_WALLET
                          assetType: USDC
                          address: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: OUTGOING_PAYMENT
      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 webhookId)
          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:
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000001
                  type: TEST
      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 webhookId)
          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/BulkUploadWebhookRequest'
            examples:
              completedUpload:
                summary: Successful bulk upload completion
                value:
                  bulkCustomerImportJob:
                    jobId: Job:019542f5-b3e7-1d02-0000-000000000006
                    status: COMPLETED
                    progress:
                      total: 5000
                      processed: 5000
                      successful: 5000
                      failed: 0
                    errors: []
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: BULK_UPLOAD
                  timestamp: '2025-08-15T14:32:00Z'
              failedUpload:
                summary: Failed bulk upload
                value:
                  bulkCustomerImportJob:
                    jobId: 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
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: BULK_UPLOAD
                  timestamp: '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 webhookId)
          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:
                  invitation:
                    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
                  timestamp: '2025-09-01T15:45:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: INVITATION_CLAIMED
      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 webhookId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  kyc-status:
    post:
      summary: KYC customer status change
      description: |
        Webhook that is called when the KYC status of a customer is updated.
        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.

        ### KYC/B Flow
        This webhook is triggered when KYC/B has reached a decision on a customer. Generally most customers will finish KYC within a few minutes. Others might be rejected because of incorrect data passed in or may have been flagged for manual review.
        The webhook will only trigger for final states. This will be APPROVED, REJECTED, EXPIRED, CANCELED, MANUALLY_APPROVED, MANUALLY_REJECTED.

          * APPROVED: The customer has been approved.
          * REJECTED: The customer has been rejected after a KYC check.
          * PENDING_REVIEW: KYC check is in progress.
          * EXPIRED: KYC check has expired. This is generally because a customer did not submit all required information needed within a session.
          * CANCELED: KYC check was canceled.
          * MANUALLY_APPROVED: The customer was manually approved.
          * MANUALLY_REJECTED: The customer was manually rejected.
          * NOT_STARTED: KYC has not started on the customer.
      operationId: kycStatusWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycStatusWebhook'
            examples:
              kycApprovedWebhook:
                summary: When a customer KYC has been approved
                value:
                  customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                  kycStatus: APPROVED
                  type: KYC_STATUS
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
      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 webhookId)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  account-status:
    post:
      summary: Account status notification webhook
      description: |
        Webhook that is called when the balance of an account 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.

        ### Account status
        When the balance of an internal account changes, we will push a notification with information on the account, the new balance, and who the account belongs to.
      operationId: accountStatusWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountStatusWebhook'
            examples:
              balanceDecrease:
                summary: A transaction just cleared a customer account and the balance has decreased
                value:
                  account:
                    accountId: Account:019542f5-b3e7-1d02-0000-000000000005
                    oldBalance:
                      amount: 50000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    newBalance:
                      amount: 10000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 019542f5-b3e7-1d02-0000-000000000001
                  timestamp: '2025-08-15T14:32:00Z'
                  webhookId: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: ACCOUNT_STATUS
      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 webhookId)
          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
      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:
          const: 401
          type: integer
          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
    Error500:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 500
          type: integer
          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
    Error400:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 400
          type: integer
          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 |
          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
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
    Error501:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 501
          type: integer
          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
    CustomerType:
      type: string
      enum:
        - INDIVIDUAL
        - BUSINESS
      description: Whether the customer is an individual or a business entity
      example: INDIVIDUAL
    IndividualCustomer:
      allOf:
        - $ref: '#/components/schemas/Customer'
        - type: object
          properties:
            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'
    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'
        kycStatus:
          $ref: '#/components/schemas/KycStatus'
        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
      discriminator:
        propertyName: customerType
        mapping:
          INDIVIDUAL: '#/components/schemas/IndividualCustomer'
          BUSINESS: '#/components/schemas/BusinessCustomer'
    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
    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:
      allOf:
        - $ref: '#/components/schemas/Customer'
        - type: object
          properties:
            address:
              $ref: '#/components/schemas/Address'
            businessInfo:
              type: object
              required:
                - legalName
              description: Additional information required for business entities
              properties:
                legalName:
                  type: string
                  description: Legal name of the business
                  example: Acme Corporation, Inc.
                registrationNumber:
                  type: string
                  description: Business registration number
                  example: BRN-123456789
                taxId:
                  type: string
                  description: Tax identification number
                  example: EIN-987654321
            beneficialOwners:
              type: array
              items:
                $ref: '#/components/schemas/UltimateBeneficialOwner'
    KycStatus:
      type: string
      enum:
        - APPROVED
        - REJECTED
        - PENDING_REVIEW
        - EXPIRED
        - CANCELED
        - MANUALLY_APPROVED
        - MANUALLY_REJECTED
      description: The current KYC status of a customer
      example: APPROVED
    IndividualCustomerUpdate:
      type: object
      required:
        - customerType
      properties:
        customerType:
          type: string
          enum:
            - INDIVIDUAL
          description: Customer type
        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'
        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.
          example: $john.doe@uma.domain.com
    BusinessCustomerUpdate:
      type: object
      required:
        - customerType
      properties:
        customerType:
          type: string
          const: BUSINESS
          description: Customer type
        umaAddress:
          type: string
          description: Optional UMA address identifier. If not provided, will be generated by the system.
          example: $acme@uma.domain.com
        businessInfo:
          type: object
          properties:
            legalName:
              type: string
              description: Legal name of the business
              example: Acme Corporation, Inc.
            registrationNumber:
              type: string
              description: Business registration number
              example: BRN-123456789
            taxId:
              type: string
              description: Tax identification number
              example: EIN-987654321
        address:
          $ref: '#/components/schemas/Address'
        beneficialOwners:
          type: array
          items:
            $ref: '#/components/schemas/UltimateBeneficialOwner'
    Error409:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 409
          type: integer
          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
    Error404:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 404
          type: integer
          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
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
    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
    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'
    PaymentClabeAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/ClabeAccountInfo'
      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
    PaymentAccountOrWalletInfo:
      type: object
      required:
        - accountType
      properties:
        accountType:
          $ref: '#/components/schemas/BankAccountOrWalletType'
      discriminator:
        propertyName: accountType
        mapping:
          CLABE: '#/components/schemas/PaymentClabeAccountInfo'
          US_ACCOUNT: '#/components/schemas/PaymentUsAccountInfo'
          PIX: '#/components/schemas/PaymentPixAccountInfo'
          IBAN: '#/components/schemas/PaymentIbanAccountInfo'
          FBO: '#/components/schemas/PaymentFboAccountInfo'
          UPI: '#/components/schemas/PaymentUpiAccountInfo'
          NGN_ACCOUNT: '#/components/schemas/PaymentNgnAccountInfo'
          SPARK_WALLET: '#/components/schemas/PaymentSparkWalletInfo'
          LIGHTNING: '#/components/schemas/PaymentLightningInvoiceInfo'
          SOLANA_WALLET: '#/components/schemas/PaymentSolanaWalletInfo'
          TRON_WALLET: '#/components/schemas/PaymentTronWalletInfo'
          POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo'
    UsAccountInfo:
      type: object
      required:
        - accountType
        - accountNumber
        - routingNumber
        - accountCategory
      properties:
        accountType:
          const: US_ACCOUNT
          example: US_ACCOUNT
        accountNumber:
          type: string
          description: US bank account number
          example: '123456789'
        routingNumber:
          type: string
          description: ACH routing number (9 digits)
          example: '987654321'
          minLength: 9
          maxLength: 9
          pattern: ^[0-9]{9}$
        accountCategory:
          type: string
          enum:
            - CHECKING
            - SAVINGS
          description: Type of account (checking or savings)
          example: CHECKING
        bankName:
          type: string
          description: Name of the bank
          example: Chase Bank
    PaymentUsAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/UsAccountInfo'
      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
    PixAccountInfo:
      type: object
      required:
        - accountType
        - pixKey
        - pixKeyType
        - taxId
      properties:
        accountType:
          const: PIX
          example: PIX
        pixKey:
          type: string
          description: PIX key for Brazilian instant payments
          example: '55119876543210'
        pixKeyType:
          type: string
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - RANDOM
          description: Type of PIX key being used
          example: PHONE
        taxId:
          type: string
          description: Tax ID of the account holder
          example: '1234567890'
    PaymentPixAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/PixAccountInfo'
    IbanAccountInfo:
      type: object
      required:
        - accountType
        - iban
        - swiftBic
      properties:
        accountType:
          const: IBAN
          example: IBAN
        iban:
          type: string
          description: International Bank Account Number
          example: DE89370400440532013000
          minLength: 15
          maxLength: 34
        swiftBic:
          type: string
          description: SWIFT/BIC code (8 or 11 characters)
          example: DEUTDEFF
          minLength: 8
          maxLength: 11
    PaymentIbanAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/IbanAccountInfo'
      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
    PaymentFboAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - type: object
          required:
            - paymentUrl
            - paymentMethod
          properties:
            paymentUrl:
              type: string
              format: uri
              description: The URL to make a request to in order to confirm payment
              example: https://api.lightspark.com/grid/2025-10-13/confirm
            paymentMethod:
              type: string
              enum:
                - POST
                - GET
              description: The HTTP method to use for confirming the payment
              example: POST
    UpiAccountInfo:
      type: object
      required:
        - accountType
        - vpa
      properties:
        accountType:
          const: UPI
          example: UPI
        vpa:
          type: string
          description: Virtual Payment Address for UPI payments
          example: somecustomers@okbank
    PaymentUpiAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/UpiAccountInfo'
    NgnAccountInfo:
      type: object
      required:
        - accountType
        - accountNumber
        - bankName
      properties:
        accountType:
          const: NGN_ACCOUNT
          example: NGN_ACCOUNT
        accountNumber:
          type: string
          description: Nigerian bank account number
          example: '0123456789'
          minLength: 10
          maxLength: 10
          pattern: ^[0-9]{10}$
        bankName:
          type: string
          description: Name of the bank
          example: First Bank of Nigeria
    PaymentNgnAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/NgnAccountInfo'
      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:
        - accountType
        - address
      properties:
        accountType:
          const: SPARK_WALLET
          example: SPARK_WALLET
        address:
          type: string
          description: Spark wallet address
          example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
    PaymentSparkWalletInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/SparkWalletInfo'
      required:
        - assetType
      properties:
        assetType:
          type: string
          description: Type of asset
          enum:
            - BTC
            - USDB
        invoice:
          type: string
          description: Invoice for the payment
          example: sparkrt1pgss8ter0fhc4c220f3zftmpz49h8wqte8eg3m5zkrraplgc048jucgszg3ssqgjzqqekv73mmh842yj7drsjwh7t7tz5zt8wf5kghm5v4ehggszppjp5s80cg3qjdzc55g2567tn3lj705hdsr577tg8ah795mlnt6807y657qhkmgfkf9w75p4wz3l8vhua85zdn6ryj32zuj0p00pv2l5z4u47mw6h4s
    PaymentLightningInvoiceInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
      required:
        - accountType
        - invoice
      properties:
        accountType:
          type: string
          enum:
            - LIGHTNING
          example: LIGHTNING
        invoice:
          type: string
          description: Invoice for the payment
          example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
    SolanaWalletInfo:
      type: object
      required:
        - accountType
        - address
      properties:
        accountType:
          const: SOLANA_WALLET
          example: SOLANA_WALLET
        address:
          type: string
          description: Solana wallet address
          example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg
    PaymentSolanaWalletInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/SolanaWalletInfo'
      properties:
        assetType:
          type: string
          description: Type of asset
          enum:
            - USDC
            - USDT
    TronWalletInfo:
      type: object
      required:
        - accountType
        - address
      properties:
        accountType:
          const: TRON_WALLET
          example: TRON_WALLET
        address:
          type: string
          description: Tron wallet address
          example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
    PaymentTronWalletInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/TronWalletInfo'
      properties:
        assetType:
          type: string
          description: Type of asset
          enum:
            - USDT
    PolygonWalletInfo:
      type: object
      required:
        - accountType
        - address
      properties:
        accountType:
          const: POLYGON_WALLET
          example: POLYGON_WALLET
        address:
          type: string
          description: Polygon eth wallet address
          example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12'
    PaymentPolygonWalletInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/PolygonWalletInfo'
      properties:
        assetType:
          type: string
          description: Type of asset
          enum:
            - USDC
    BankAccountOrWalletType:
      type: string
      enum:
        - CLABE
        - US_ACCOUNT
        - PIX
        - IBAN
        - FBO
        - UPI
        - NGN_ACCOUNT
        - SPARK_WALLET
        - LIGHTNING
        - SOLANA_WALLET
        - TRON_WALLET
        - POLYGON_WALLET
        - BASE_WALLET
      description: Type of account or wallet information
    ClabeAccountInfo:
      type: object
      required:
        - accountType
        - clabeNumber
      properties:
        accountType:
          const: CLABE
          example: CLABE
        clabeNumber:
          type: string
          description: 18-digit CLABE number (Mexican banking standard)
          example: '123456789012345678'
          minLength: 18
          maxLength: 18
          pattern: ^[0-9]{18}$
    BaseWalletInfo:
      type: object
      required:
        - accountType
        - address
      properties:
        accountType:
          const: BASE_WALLET
          example: BASE_WALLET
        address:
          type: string
          description: Base eth wallet address
          example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12'
    PaymentBaseWalletInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentAccountOrWalletInfo'
        - $ref: '#/components/schemas/BaseWalletInfo'
      properties:
        assetType:
          type: string
          description: Type of asset
          enum:
            - USDC
    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
        accountOrWalletInfo:
          oneOf:
            - title: CLABE Account
              $ref: '#/components/schemas/PaymentClabeAccountInfo'
            - title: US Bank Account
              $ref: '#/components/schemas/PaymentUsAccountInfo'
            - title: PIX Account
              $ref: '#/components/schemas/PaymentPixAccountInfo'
            - title: IBAN Account
              $ref: '#/components/schemas/PaymentIbanAccountInfo'
            - title: FBO Account
              $ref: '#/components/schemas/PaymentFboAccountInfo'
            - title: UPI Account
              $ref: '#/components/schemas/PaymentUpiAccountInfo'
            - title: Spark Wallet
              $ref: '#/components/schemas/PaymentSparkWalletInfo'
            - title: Lightning Invoice
              $ref: '#/components/schemas/PaymentLightningInvoiceInfo'
            - title: Solana Wallet
              $ref: '#/components/schemas/PaymentSolanaWalletInfo'
            - title: Tron Wallet
              $ref: '#/components/schemas/PaymentTronWalletInfo'
            - title: Polygon Wallet
              $ref: '#/components/schemas/PaymentPolygonWalletInfo'
            - title: Base Wallet
              $ref: '#/components/schemas/PaymentBaseWalletInfo'
          discriminator:
            propertyName: accountType
            mapping:
              CLABE: '#/components/schemas/PaymentClabeAccountInfo'
              US_ACCOUNT: '#/components/schemas/PaymentUsAccountInfo'
              PIX: '#/components/schemas/PaymentPixAccountInfo'
              IBAN: '#/components/schemas/PaymentIbanAccountInfo'
              FBO: '#/components/schemas/PaymentFboAccountInfo'
              UPI: '#/components/schemas/PaymentUpiAccountInfo'
              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'
    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
    IndividualBeneficiary:
      type: object
      required:
        - fullName
        - birthDate
        - nationality
        - beneficiaryType
      properties:
        beneficiaryType:
          type: string
          const: INDIVIDUAL
          example: INDIVIDUAL
        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'
    BusinessBeneficiary:
      type: object
      required:
        - legalName
        - beneficiaryType
      properties:
        beneficiaryType:
          type: string
          const: BUSINESS
          example: BUSINESS
        legalName:
          type: string
          description: Legal name of the business
          example: Acme Corporation, Inc.
        registrationNumber:
          type: string
          description: Business registration number
          example: BRN-123456789
        taxId:
          type: string
          description: Tax identification number
          example: EIN-987654321
        address:
          $ref: '#/components/schemas/Address'
    UsAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/UsAccountInfo'
        - type: object
          required:
            - accountType
            - beneficiary
          properties:
            accountType:
              const: US_ACCOUNT
              example: US_ACCOUNT
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    ClabeAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/ClabeAccountInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: CLABE
              example: CLABE
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    PixAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PixAccountInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: PIX
              example: PIX
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    IbanAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/IbanAccountInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: IBAN
              example: IBAN
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    UpiAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/UpiAccountInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: UPI
              example: UPI
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    NgnAccountExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/NgnAccountInfo'
        - type: object
          required:
            - accountType
            - purposeOfPayment
            - beneficiary
          properties:
            accountType:
              const: NGN_ACCOUNT
              example: NGN_ACCOUNT
            beneficiary:
              oneOf:
                - $ref: '#/components/schemas/IndividualBeneficiary'
                - $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
            purposeOfPayment:
              type: string
              enum:
                - GIFT
                - SELF
                - GOODS_OR_SERVICES
                - EDUCATION
                - HEALTH_OR_MEDICAL
                - REAL_ESTATE_PURCHASE
                - LOAN_PAYMENT
                - TAX_PAYMENT
                - UTILITY_BILL
                - DONATION
                - TRAVEL
                - OTHER
              description: Purpose of payment
              example: GOODS_OR_SERVICES
    SparkWalletExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/SparkWalletInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: SPARK_WALLET
              example: SPARK_WALLET
    LightningExternalAccountInfo:
      type: object
      required:
        - accountType
      description: |
        Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided.
      properties:
        accountType:
          const: LIGHTNING
          example: 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
    SolanaWalletExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/SolanaWalletInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: SOLANA_WALLET
              example: SOLANA_WALLET
    TronWalletExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/TronWalletInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: TRON_WALLET
              example: TRON_WALLET
    PolygonWalletExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PolygonWalletInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: POLYGON_WALLET
              example: POLYGON_WALLET
    BaseWalletExternalAccountInfo:
      allOf:
        - $ref: '#/components/schemas/BaseWalletInfo'
        - type: object
          required:
            - accountType
          properties:
            accountType:
              const: BASE_WALLET
              example: BASE_WALLET
    ExternalAccountInfo:
      oneOf:
        - title: US Account
          $ref: '#/components/schemas/UsAccountExternalAccountInfo'
        - title: CLABE Account
          $ref: '#/components/schemas/ClabeAccountExternalAccountInfo'
        - title: PIX Account
          $ref: '#/components/schemas/PixAccountExternalAccountInfo'
        - title: IBAN Account
          $ref: '#/components/schemas/IbanAccountExternalAccountInfo'
        - title: UPI Account
          $ref: '#/components/schemas/UpiAccountExternalAccountInfo'
        - title: NGN Account
          $ref: '#/components/schemas/NgnAccountExternalAccountInfo'
        - title: Spark Wallet
          $ref: '#/components/schemas/SparkWalletExternalAccountInfo'
        - title: Lightning
          $ref: '#/components/schemas/LightningExternalAccountInfo'
        - title: Solana Wallet
          $ref: '#/components/schemas/SolanaWalletExternalAccountInfo'
        - title: Tron Wallet
          $ref: '#/components/schemas/TronWalletExternalAccountInfo'
        - title: Polygon Wallet
          $ref: '#/components/schemas/PolygonWalletExternalAccountInfo'
        - title: Base Wallet
          $ref: '#/components/schemas/BaseWalletExternalAccountInfo'
      discriminator:
        propertyName: accountType
        mapping:
          US_ACCOUNT: '#/components/schemas/UsAccountExternalAccountInfo'
          CLABE: '#/components/schemas/ClabeAccountExternalAccountInfo'
          PIX: '#/components/schemas/PixAccountExternalAccountInfo'
          IBAN: '#/components/schemas/IbanAccountExternalAccountInfo'
          UPI: '#/components/schemas/UpiAccountExternalAccountInfo'
          NGN_ACCOUNT: '#/components/schemas/NgnAccountExternalAccountInfo'
          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'
    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
            accountInfo:
              $ref: '#/components/schemas/ExternalAccountInfo'
    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
            accountInfo:
              $ref: '#/components/schemas/ExternalAccountInfo'
    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
    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:
          oneOf:
            - title: Account Destination
              type: object
              required:
                - accountId
                - currency
              properties:
                accountId:
                  type: string
                  description: Destination account identifier
                  example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                currency:
                  type: string
                  description: Currency code for the destination account
                  example: EUR
              description: Destination account details
            - title: UMA Address Destination
              type: object
              required:
                - umaAddress
              properties:
                umaAddress:
                  type: string
                  description: UMA address of the recipient
                  example: $receiver@uma.domain.com
                currency:
                  type: string
                  description: Currency code for the destination
                  example: EUR
        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:
          type: object
          description: Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.
          additionalProperties: true
          example:
            FULL_NAME: John Sender
            BIRTH_DATE: '1985-06-15'
            NATIONALITY: DE
      discriminator:
        propertyName: type
        mapping:
          INCOMING: '#/components/schemas/IncomingTransaction'
          OUTGOING: '#/components/schemas/OutgoingTransaction'
    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:
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          required:
            - receivedAmount
          properties:
            source:
              oneOf:
                - title: Account Source
                  type: object
                  required:
                    - accountId
                    - currency
                  properties:
                    accountId:
                      type: string
                      description: Source account identifier
                      example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                    currency:
                      type: string
                      description: Currency code for the source account
                      example: USD
                  description: Source account details
                - title: UMA Address Source
                  type: object
                  required:
                    - umaAddress
                  properties:
                    umaAddress:
                      type: string
                      description: UMA address of the sender
                      example: $sender@uma.domain.com
                    currency:
                      type: string
                      description: Currency code for the source
                      example: USD
                  description: UMA address source details
            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.
    Refund:
      type: object
      required:
        - reference
        - initiatedAt
      properties:
        reference:
          type: string
          description: The unique reference code 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 or will be settled
          example: '2025-08-15T14:30:00Z'
    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:
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          required:
            - sentAmount
            - paymentInstructions
            - source
          properties:
            source:
              oneOf:
                - title: Account Source
                  type: object
                  required:
                    - accountId
                    - currency
                  properties:
                    accountId:
                      type: string
                      description: Source account identifier
                      example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                    currency:
                      type: string
                      description: Currency code for the source account
                      example: USD
                  description: Source account details
                - title: UMA Address Source
                  type: object
                  required:
                    - umaAddress
                  properties:
                    umaAddress:
                      type: string
                      description: UMA address of the sender
                      example: $sender@uma.domain.com
                    currency:
                      type: string
                      description: Currency code for the source
                      example: USD
                  description: UMA address source details
            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
            originalTransactionId:
              type: string
              description: ID of the original transaction that this transaction is retrying, if applicable
              example: Transaction:019542f5-b3e7-1d02-0000-000000000003
            paymentInstructions:
              type: array
              description: Payment instructions for executing the payment.
              items:
                $ref: '#/components/schemas/PaymentInstructions'
              example:
                - accountType: US_ACCOUNT
                  accountNumber: '1234567890'
                  routingNumber: '021000021'
                  bankName: Chase Bank
                  referenceCode: REF123456
                - accountType: SPARK_WALLET
                  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.
    TransactionStatus:
      type: string
      enum:
        - CREATED
        - PENDING
        - PROCESSING
        - COMPLETED
        - REJECTED
        - FAILED
        - REFUNDED
        - EXPIRED
      description: Status of a payment transaction
    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:
          const: 412
          type: integer
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | UNSUPPORTED_UMA_VERSION | Counterparty doesn't support the Grid UMA version |
          const: UNSUPPORTED_UMA_VERSION
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
    Error424:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 424
          type: integer
          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
    QuoteSource:
      oneOf:
        - title: Account
          type: object
          required:
            - accountId
          properties:
            accountId:
              type: string
              description: Source account identifier
              example: InternalAccount:85dcbd6-dced-4ec4-b756-3c3a9ea3d965
            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
          description: Source account details
        - title: Real-time funding
          type: object
          required:
            - currency
            - customerId
          properties:
            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
          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.).
    Quote:
      type: object
      required:
        - quoteId
        - status
        - expiresAt
        - createdAt
        - source
        - destination
        - sendingCurrency
        - receivingCurrency
        - totalSendingAmount
        - totalReceivingAmount
        - exchangeRate
        - feesIncluded
        - transactionId
      properties:
        quoteId:
          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/QuoteSource'
        destination:
          oneOf:
            - title: Account Destination
              type: object
              required:
                - accountId
              properties:
                accountId:
                  type: string
                  description: Destination account identifier
                  example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                currency:
                  type: string
                  description: Currency code for the destination account
                  example: EUR
              description: Destination account details
            - title: UMA Address Destination
              type: object
              required:
                - umaAddress
              properties:
                umaAddress:
                  type: string
                  description: UMA address of the recipient
                  example: $receiver@uma.domain.com
                currency:
                  type: string
                  description: Currency code for the destination
                  example: EUR
                counterpartyInformation:
                  type: object
                  description: Information about the recipient, as required by the platform in their configuration.
                  additionalProperties: true
                  example:
                    FULL_NAME: Jane Receiver
                    BIRTH_DATE: '1990-01-01'
                    NATIONALITY: FR
              description: UMA address destination details
        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:
            - accountType: US_ACCOUNT
              accountNumber: '1234567890'
              routingNumber: '021000021'
              bankName: Chase Bank
              referenceCode: REF123456
            - accountType: SPARK_WALLET
              address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
              invoice: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
        transactionId:
          type: string
          description: The ID of the transaction created from this quote.
          example: Transaction:019542f5-b3e7-1d02-0000-000000000005
        originalQuoteId:
          description: ID of the quote that is being retried
          type: string
          example: Quote:019542f5-b3e7-1d02-0000-000000000001
        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).
    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/QuoteSource'
        destination:
          oneOf:
            - title: Account
              type: object
              required:
                - accountId
                - currency
              properties:
                accountId:
                  type: string
                  description: Destination account identifier
                  example: a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                currency:
                  type: string
                  description: Currency code for the destination account. 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: Destination account details
            - title: UMA Address
              type: object
              required:
                - umaAddress
                - currency
              properties:
                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
            - title: External Account Details
              type: object
              required:
                - externalAccountDetails
              properties:
                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 external accounts endpoints for test values in sandbox mode.
        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.
          example: false
        description:
          type: string
          description: Optional description/memo for the transfer
          example: 'Invoice #1234 payment'
        senderCustomerInfo:
          type: object
          additionalProperties: true
          description: |
            Only relevant for UMA destinations.
            Key-value pairs of information about the sender which was requested by the counterparty (recipient) institution.
            Any fields specified in `requiredPayerDataFields` from the response of the `/receiver/uma/{receiverUmaAddress}` (lookupUma) endpoint
            MUST be provided here if they were requested. If the counterparty (recipient) institution did not request any information, this field can be omitted.
          example:
            FULL_NAME: Jane Receiver
            NATIONALITY: FR
    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
    BulkCustomerImportJob:
      type: object
      required:
        - jobId
        - status
        - progress
      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
            - 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:
            type: object
            required:
              - correlationId
              - error
            properties:
              correlationId:
                type: string
                description: Platform customer ID or row number for the failed entry
                example: biz456
              error:
                $ref: '#/components/schemas/Error'
        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'
    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.
    Error403:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          const: 403
          type: integer
          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
    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'
    IncomingPaymentWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - transaction
          properties:
            transaction:
              $ref: '#/components/schemas/IncomingTransaction'
            type:
              $ref: '#/components/schemas/WebhookType'
              description: Type of webhook event
              example: INCOMING_PAYMENT
            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.
    BaseWebhook:
      type: object
      required:
        - timestamp
        - webhookId
        - type
      properties:
        timestamp:
          type: string
          format: date-time
          description: ISO8601 timestamp when the webhook was sent (can be used to prevent replay attacks)
          example: '2025-08-15T14:32:00Z'
        webhookId:
          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: Type of webhook event
      discriminator:
        propertyName: type
        mapping:
          INCOMING_PAYMENT: '#/components/schemas/IncomingPaymentWebhook'
          OUTGOING_PAYMENT: '#/components/schemas/OutgoingPaymentWebhook'
          TEST: '#/components/schemas/TestWebhookRequest'
          BULK_UPLOAD: '#/components/schemas/BulkUploadWebhookRequest'
          INVITATION_CLAIMED: '#/components/schemas/InvitationClaimedWebhook'
          KYC_STATUS: '#/components/schemas/KycStatusWebhook'
    WebhookType:
      type: string
      enum:
        - INCOMING_PAYMENT
        - OUTGOING_PAYMENT
        - TEST
        - BULK_UPLOAD
        - INVITATION_CLAIMED
        - KYC_STATUS
        - ACCOUNT_STATUS
      description: Type of webhook event, used by the receiver to identify which webhook is being received
    OutgoingPaymentWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - transaction
          properties:
            transaction:
              $ref: '#/components/schemas/OutgoingTransaction'
            type:
              $ref: '#/components/schemas/WebhookType'
              description: Type of webhook event
              example: OUTGOING_PAYMENT
    TestWebhookRequest:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/WebhookType'
              description: Type of webhook event
              example: TEST
    BulkUploadWebhookRequest:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - bulkCustomerImportJob
          properties:
            bulkCustomerImportJob:
              $ref: '#/components/schemas/BulkCustomerImportJob'
            type:
              $ref: '#/components/schemas/WebhookType'
              description: Type of webhook event
              example: BULK_UPLOAD
    InvitationClaimedWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - invitation
          properties:
            invitation:
              $ref: '#/components/schemas/UmaInvitation'
            type:
              type: string
              const: INVITATION_CLAIMED
              description: Type of webhook event
              example: INVITATION_CLAIMED
    KycStatusWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - customerId
            - kycStatus
          properties:
            customerId:
              type: string
              description: System generated id of the customer
              example: Customer:019542f5-b3e7-1d02-0000-000000000001
            kycStatus:
              $ref: '#/components/schemas/KycStatus'
    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/Error'
        - 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/Error'
        - 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
    AccountStatusWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - accountId
          properties:
            accountId:
              type: string
              description: The id of the account whose balance has changed
            oldBalance:
              $ref: '#/components/schemas/CurrencyAmount'
            newBalance:
              $ref: '#/components/schemas/CurrencyAmount'
            customerId:
              type: string
              description: The ID of the customer associated with the internal account
              example: Customer:019542f5-b3e7-1d02-0000-000000000001
            platformCustomerId:
              type: string
              description: The ID of the customer as associated in your platform
              example: 019542f5-b3e7-1d02-0000-000000000001