openapi.yaml

openapi: 3.1.0
info:
  title: UMA as a Service (UMAaaS) API
  description: |
    API for managing global payments to and from UMA addresses. 
    This service facilitates cross-currency financial transactions using simple human-readable UMA addresses.
  version: '2025-05-15'
  contact:
    name: Lightspark Support
    email: support@lightspark.com
  license:
    name: Proprietary
    url: https://lightspark.com/terms
servers:
  - url: https://api.uma.money/umaaas/2025-05-15
    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 UMAaas dashboard.
  - name: Users
    description: User management endpoints for creating and updating user information
  - name: Transactions
    description: Endpoints for retrieving transaction information
  - name: Sending Payments
    description: Endpoints for creating and managing payment quotes and executing payments
  - 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 programatically manage API tokens
paths:
  /users:
    post:
      summary: Add a new user
      description: Register a new user in the system with UMA address and bank account information
      operationId: createUser
      tags:
        - Users
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/IndividualUser'
                - $ref: '#/components/schemas/BusinessUser'
              discriminator:
                propertyName: userType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IndividualUser'
                  BUSINESS: '#/components/schemas/BusinessUser'
            examples:
              individualUser:
                summary: Create individual user example
                value:
                  umaAddress: $jane.doe@uma.domain.com
                  platformUserId: 7b3c5a89d2f1e0
                  userType: INDIVIDUAL
                  fullName: Jane Doe
                  birthDate: '1992-03-25'
                  address:
                    line1: 123 Pine Street
                    line2: Unit 501
                    city: Seattle
                    state: WA
                    postalCode: '98101'
                    country: US
                  bankAccountInfo:
                    accountType: US_ACCOUNT
                    accountNumber: '12345678901'
                    routingNumber: '123456789'
                    accountCategory: CHECKING
                    bankName: Chase Bank
                    platformAccountId: chase_primary_1234
              businessUser:
                summary: Create business user example
                value:
                  umaAddress: $acme@uma.domain.com
                  platformUserId: 6e4d2c0b8a9f3
                  userType: BUSINESS
                  businessInfo:
                    legalName: Acme Corporation
                    registrationNumber: BRN-456789123
                    taxId: EIN-987123456
                  address:
                    line1: 400 Commerce Way
                    city: Austin
                    state: TX
                    postalCode: '78701'
                    country: US
                  bankAccountInfo:
                    accountType: US_ACCOUNT
                    accountNumber: '98765432109'
                    routingNumber: '987654321'
                    accountCategory: CHECKING
                    bankName: Bank of America
                    platformAccountId: boa_business_5678
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IndividualUser'
                  - $ref: '#/components/schemas/BusinessUser'
                discriminator:
                  propertyName: userType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualUser'
                    BUSINESS: '#/components/schemas/BusinessUser'
        '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 - User 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 users
      description: |
        Retrieve a list of users with optional filtering parameters. Returns all users that match
        the specified filters. If no filters are provided, returns all users (paginated).
      operationId: listUsers
      tags:
        - Users
      security:
        - BasicAuth: []
      parameters:
        - name: platformUserId
          in: query
          description: Filter by platform-specific user identifier
          required: false
          schema:
            type: string
        - name: umaAddress
          in: query
          description: Filter by UMA address
          required: false
          schema:
            type: string
        - name: userType
          in: query
          description: Filter by user type
          required: false
          schema:
            $ref: '#/components/schemas/UserType'
        - name: createdAfter
          in: query
          description: Filter users created after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter users created before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedAfter
          in: query
          description: Filter users updated after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedBefore
          in: query
          description: Filter users 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: isIncludingDeleted
          in: query
          description: Whether to include deleted users 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 users matching the filter criteria
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/IndividualUser'
                        - $ref: '#/components/schemas/BusinessUser'
                      discriminator:
                        propertyName: userType
                        mapping:
                          INDIVIDUAL: '#/components/schemas/IndividualUser'
                          BUSINESS: '#/components/schemas/BusinessUser'
                  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 users 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'
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        description: System-generated unique user identifier
        required: true
        schema:
          type: string
    get:
      summary: Get user by ID
      description: Retrieve a user by their system-generated ID
      operationId: getUserById
      tags:
        - Users
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IndividualUser'
                  - $ref: '#/components/schemas/BusinessUser'
                discriminator:
                  propertyName: userType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualUser'
                    BUSINESS: '#/components/schemas/BusinessUser'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: User 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 user by ID
      description: Update a user's metadata by their system-generated ID
      operationId: updateUserById
      tags:
        - Users
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  title: individualUpdate
                  properties:
                    umaAddress:
                      type: string
                      description: Full UMA address
                    fullName:
                      type: string
                      description: Individual's full name
                    birthDate:
                      type: string
                      format: date
                      description: Date of birth in ISO 8601 format (YYYY-MM-DD)
                    nationality:
                      type: string
                      description: Country code (ISO 3166-1 alpha-2)
                    address:
                      $ref: '#/components/schemas/Address'
                    bankAccountInfo:
                      $ref: '#/components/schemas/UserBankAccountInfo'
                - type: object
                  title: businessUpdate
                  properties:
                    umaAddress:
                      type: string
                      description: Full UMA address
                    businessInfo:
                      type: object
                      properties:
                        legalName:
                          type: string
                          description: Legal name of the business
                        registrationNumber:
                          type: string
                          description: Business registration number
                        taxId:
                          type: string
                          description: Tax identification number
                    address:
                      $ref: '#/components/schemas/Address'
                    bankAccountInfo:
                      $ref: '#/components/schemas/UserBankAccountInfo'
            examples:
              individualUpdate:
                summary: Update individual user example
                value:
                  userType: INDIVIDUAL
                  fullName: John Smith
                  birthDate: '1985-06-15'
                  address:
                    line1: 456 Market St
                    city: San Francisco
                    state: CA
                    postalCode: '94103'
                    country: US
                  bankAccountInfo:
                    accountType: US_ACCOUNT
                    accountNumber: '11122233344'
                    routingNumber: '111222333'
                    accountCategory: CHECKING
                    bankName: Wells Fargo
                    platformAccountId: wf_checking_9012
              businessUpdate:
                summary: Update business user example
                value:
                  userType: 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
                  bankAccountInfo:
                    accountType: US_ACCOUNT
                    accountNumber: '55566677788'
                    routingNumber: '555666777'
                    accountCategory: CHECKING
                    bankName: JP Morgan Chase
                    platformAccountId: chase_business_3456
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IndividualUser'
                  - $ref: '#/components/schemas/BusinessUser'
                discriminator:
                  propertyName: userType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualUser'
                    BUSINESS: '#/components/schemas/BusinessUser'
        '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: User 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 user by ID
      description: Delete a user by their system-generated ID
      operationId: deleteUserById
      tags:
        - Users
      security:
        - BasicAuth: []
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IndividualUser'
                  - $ref: '#/components/schemas/BusinessUser'
                discriminator:
                  propertyName: userType
                  mapping:
                    INDIVIDUAL: '#/components/schemas/IndividualUser'
                    BUSINESS: '#/components/schemas/BusinessUser'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '410':
          description: User deleted already
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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 UMAaaS 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 users created after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter users created before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedAfter
          in: query
          description: Filter users updated after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedBefore
          in: query
          description: Filter users 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'
  /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'
  /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'
  /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:
    get:
      summary: List transactions
      description: |
        Retrieve a paginated list of transactions with optional filtering.
        The transactions can be filtered by user ID, platform user ID, UMA address, 
        date range, status, and transaction type.
      operationId: listTransactions
      tags:
        - Transactions
      security:
        - BasicAuth: []
      parameters:
        - name: userId
          in: query
          description: Filter by system user ID
          required: false
          schema:
            type: string
        - name: platformUserId
          in: query
          description: Filter by platform-specific user ID
          required: false
          schema:
            type: string
        - name: umaAddress
          in: query
          description: Filter by UMA address (either sender or receiver)
          required: false
          schema:
            type: string
        - name: senderUmaAddress
          in: query
          description: Filter by sender UMA address
          required: false
          schema:
            type: string
        - name: receiverUmaAddress
          in: query
          description: Filter by receiver UMA address
          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}/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:
                receiverUserInfo:
                  type: object
                  additionalProperties: true
                  description: Information about the recipient, provided by the platform if requested in the original webhook via `requestedReceiverUserInfoFields`.
      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'
  /receiver/{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:
        - Sending Payments
      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 userId is provided)
          required: false
          schema:
            type: string
        - name: userId
          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:
                type: object
                required:
                  - receiverUmaAddress
                  - supportedCurrencies
                  - lookupId
                  - kycStatus
                properties:
                  receiverUmaAddress:
                    type: string
                    description: The UMA address that was looked up
                    example: $receiver@uma.domain
                  supportedCurrencies:
                    type: array
                    description: List of currencies supported by the receiving UMA address
                    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
                  kycStatus:
                    type: string
                    description: KYC status of the customer. This field describes whether the UMA provider is doing a full KYC check on the customer. Note that in cases where the UMA provider is proxying to an underlying bank account, the bank will still have KYC'd the customer. See `bankAccountNameMatchingStatus` for cases where there's a backing bank account, but the UMA provider is able to verify the account holder's name.
                    example: VERIFIED
                    enum:
                      - UNKNOWN
                      - NOT_VERIFIED
                      - PENDING
                      - VERIFIED
                  bankAccountNameMatchingStatus:
                    type: string
                    description: Status of the bank account name matching. This field describes whether the UMA provider is able to verify that a backing bank account holder's name matches the name provided as payee data in the payreq response if applicable. It ensures that the ultimate landing destination of the payment is the intended payee. Note that this field is only applicable if the UMA provider is proxying to an underlying bank account.
                    example: MATCHED
                    enum:
                      - UNKNOWN
                      - NOT_MATCHED
                      - MATCHED
        '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'
  /quotes:
    post:
      summary: Create a payment quote
      description: |
        Generate a quote for a payment from one UMA address to another.
        The quote locks in exchange rates and fees for a set period of time and provides
        payment instructions that can be used to execute the payment.

        Depending on the `lockedCurrencySide` parameter, either the sending amount or 
        receiving amount will be locked.

        The returned quote includes payment instructions with the banking details
        needed to execute the payment and fulfill the quote. These instructions
        must be followed precisely, including any reference codes provided.
      operationId: createQuote
      tags:
        - Sending Payments
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lookupId
                - sendingCurrencyCode
                - receivingCurrencyCode
                - lockedCurrencySide
                - lockedCurrencyAmount
              properties:
                lookupId:
                  type: string
                  description: Unique identifier for the prior receiver uma address lookup request.
                  example: Lookup:019542f5-b3e7-1d02-0000-000000000009
                sendingCurrencyCode:
                  type: string
                  description: Currency code for the sending amount
                  example: USD
                receivingCurrencyCode:
                  type: string
                  description: Currency code for the receiving amount
                  example: EUR
                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
                description:
                  type: string
                  description: Optional description/memo for the payment
                  example: 'Invoice #1234 payment'
                senderUserInfo:
                  type: object
                  additionalProperties: true
                  description: |
                    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/{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
            examples:
              lockSendAmount:
                summary: Lock sending amount
                value:
                  lookupId: LookupRequest:019542f5-b3e7-1d02-0000-000000000009
                  sendingCurrencyCode: USD
                  receivingCurrencyCode: EUR
                  lockedCurrencySide: SENDING
                  lockedCurrencyAmount: 1000
                  description: 'Payment for invoice #1234'
              lockReceiveAmount:
                summary: Lock receiving amount
                value:
                  lookupId: LookupRequest:019542f5-b3e7-1d02-0000-000000000009
                  sendingCurrencyCode: USD
                  receivingCurrencyCode: EUR
                  lockedCurrencySide: RECEIVING
                  lockedCurrencyAmount: 9200
      responses:
        '201':
          description: |
            Quote created successfully. The response includes payment instructions
            that the client can use to execute the payment through their banking provider.
          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'
  /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:
        - Sending Payments
      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/{quoteId}/retry:
    post:
      summary: Retry an incomplete payment
      description: |
        In the case where a customer is debited but the Lightning payment fails to complete, integrators can retry the payment using this endpoint.  

        Payments retried with this endpoint will debit from the sender and deliver to the recipient the same amount as the original quote.
        As UMA as a service does not persist customer PII, retries need to start with a lookup request to retrieve the original quote's recipient counter party data requirements then pass that sender information in the request body.
        Before calling this endpoint, you should reach out to the UMA as a service team to investigate the underlying issue.  As part of resolution, they'll update the transaction to the appropriate state.  The quote / transaction to retry must be in a `FAILED` or `REFUNDED` state.
      operationId: retryQuote
      tags:
        - Sending Payments
      security:
        - BasicAuth: []
      parameters:
        - name: quoteId
          in: path
          description: ID of the quote to retry
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - lookupId
              properties:
                lookupId:
                  type: string
                  description: Unique identifier for the prior receiver uma address lookup request.
                  example: Lookup:019542f5-b3e7-1d02-0000-000000000009
                senderUserInfo:
                  type: object
                  additionalProperties: true
                  description: |
                    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/{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
      responses:
        '201':
          description: |
            Quote created successfully. The response includes payment instructions
            that the client can use to execute the payment through their banking provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: |
            Unprocessable Entity - Additional counterparty information required,
            or the payment cannot be completed for another reason.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      code:
                        example: MISSING_MANDATORY_USER_INFO
                      message:
                        example: Additional counterparty information required
                      details:
                        example:
                          requiredFields:
                            - TAX_ID
                            - REGISTRATION_NUMBER
  /fbo/confirm/{quoteId}:
    post:
      summary: Trigger payment from a FBO account
      description: |
        This endpoint should only be used for when your account is configured for FBO payments.  It triggers funding a quote from your FBO account to initiate payment.
      operationId: fboConfirm
      tags:
        - Sending Payments
      security:
        - BasicAuth: []
      parameters:
        - name: quoteId
          in: path
          description: ID of the quote to pay from FBO
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Payment successful.  This updates the transaction to PROCESSING.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/bulk/csv:
    post:
      summary: Upload users via CSV file
      description: |
        Upload a CSV file containing user information for bulk creation. The CSV file should follow
        a specific format with required and optional columns based on user type.

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

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

        Required columns for individual users:
        - 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)
        - accountType: Bank account type (CLABE, US_ACCOUNT, PIX, IBAN)
        - accountNumber: Bank account number
        - bankName: Name of the bank

        Required columns for business users:
        - 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)
        - accountType: Bank account type (CLABE, US_ACCOUNT, PIX, IBAN)
        - accountNumber: Bank account number
        - bankName: Name of the bank

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

        Optional columns for individual users:
        - email: User's email address

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

        Additional required columns based on account type:

        For US_ACCOUNT:
        - routingNumber: ACH routing number (9 digits)
        - accountCategory: Either "CHECKING" or "SAVINGS"

        For CLABE:
        - clabeNumber: 18-digit CLABE number

        For PIX:
        - pixKey: PIX key value
        - pixKeyType: Type of PIX key (CPF, CNPJ, EMAIL, PHONE, RANDOM)

        For IBAN:
        - iban: International Bank Account Number
        - swiftBic: SWIFT/BIC code (8 or 11 characters)

        See the UserBankAccountInfo and UserInfo schemas for more details on the required and optional fields.

        ### Example CSV
        ```csv
        umaAddress,platformUserId,userType,fullName,birthDate,addressLine1,city,state,postalCode,country,accountType,accountNumber,bankName,platformAccountId,businessLegalName,routingNumber,accountCategory
        john.doe@uma.domain.com,user123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US,US_ACCOUNT,123456789,Chase Bank,chase_primary_1234,,222888888,SAVINGS
        acme@uma.domain.com,biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US,US_ACCOUNT,987654321,Bank of America,boa_business_5678,Acme Corp,121212121,CHECKING
        ```

        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 `/users/bulk/jobs/{jobId}` endpoint.
      operationId: uploadUsersCsv
      tags:
        - Users
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file containing user 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'
  /users/bulk/jobs/{jobId}:
    get:
      summary: Get bulk import job status
      description: |
        Retrieve the current status and results of a bulk user 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: getBulkUserImportJob
      tags:
        - Users
      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/BulkUserImportJob'
        '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 user.
      description: |
        Create an UMA invitation from a given platform user.
      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 user creating the invitation
                  example: $inviter@uma.domain
                firstName:
                  type: string
                  description: First name of the inviter to show as part of the invite
                  example: Alice
                amountToSend:
                  description: |
                    An amount to send (in the smallest unit of the user'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: '2023-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 users to accept invitations sent to them by other UMA users.
      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 user 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:
                - reference
                - currencyCode
                - currencyAmount
              properties:
                reference:
                  type: string
                  description: The unique reference code that was in the payment instructions
                  example: UMA-Q12345-REF
                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)
                  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: Reference not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /sandbox/receive:
    post:
      summary: Simulate payment send to test receiving a payment
      description: |
        Simulate sending payment from an sandbox uma address to a platform user 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.umaaas.uma.money
                receiverUmaAddress:
                  type: string
                  description: UMA address of the receiver (optional if userId is provided)
                  example: $receiver@uma.domain
                userId:
                  type: string
                  description: System ID of the receiver (optional if receiverUmaAddress is provided)
                  example: User: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'
  /uma-providers:
    get:
      summary: This endpoint provides a list of counterparties that are available.
      description: |
        This endpoint provides a list of counterparties 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 Umaaas
                    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'
webhooks:
  incoming-payment:
    post:
      summary: Incoming payment webhook and approval mechanism
      description: |
        Webhook that is called when an incoming payment is received by a user's UMA address.
        This endpoint should be implemented by clients of the UMAaas API.

        ### Authentication
        The webhook includes a signature in the `X-UMAaas-Signature` header that allows you to verify that the webhook was sent by UMAaas.
        To verify the signature:
        1. Get the UMAaas 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 UMAaas 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
                    userId: User:019542f5-b3e7-1d02-0000-000000000001
                    platformUserId: 18d3e5f7b4a9c2
                    reconciliationInstructions:
                      reference: REF-123456789
                    counterpartyInformation:
                      FULL_NAME: John Sender
                      BIRTH_DATE: '1985-06-15'
                      NATIONALITY: US
                  requestedReceiverUserInfoFields:
                    - name: NATIONALITY
                      mandatory: true
                    - name: POSTAL_ADDRESS
                      mandatory: false
                  timestamp: '2023-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
                    userId: User:019542f5-b3e7-1d02-0000-000000000001
                    platformUserId: 18d3e5f7b4a9c2
                    settledAt: '2023-08-15T14:30:00Z'
                    createdAt: '2023-08-15T14:25:18Z'
                    description: Payment for services
                    reconciliationInstructions:
                      reference: REF-123456789
                  timestamp: '2023-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 `requestedReceiverUserInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverUserInfo` 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/Error403'
        '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 UMAaas API.

        ### Authentication
        The webhook includes a signature in the `X-UMAaas-Signature` header that allows you to verify that the webhook was sent by UMAaas.
        To verify the signature:
        1. Get the UMAaas 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
                    userId: User:019542f5-b3e7-1d02-0000-000000000001
                    platformUserId: 18d3e5f7b4a9c2
                    settledAt: '2023-08-15T14:30:00Z'
                    createdAt: '2023-08-15T14:25:18Z'
                    description: 'Payment for invoice #1234'
                    exchangeRate: 0.92
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    paymentInstructions:
                      reference: UMA-Q12345-REF
                      bankAccountInfo:
                        accountType: US_ACCOUNT
                        accountNumber: 987654321
                        routingNumber: 123456789
                        accountCategory: CHECKING
                        bankName: Chase Bank
                  timestamp: '2023-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
                    userId: User:019542f5-b3e7-1d02-0000-000000000001
                    platformUserId: 18d3e5f7b4a9c2
                    createdAt: '2023-08-15T14:25:18Z'
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    paymentInstructions:
                      reference: UMA-Q12345-REF
                      bankAccountInfo:
                        accountType: US_ACCOUNT
                        accountNumber: 987654321
                        routingNumber: 123456789
                        accountCategory: CHECKING
                        bankName: Chase Bank
                  timestamp: '2023-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-UMAaas-Signature` header that allows you to verify that the webhook was sent by UMAaas.
        To verify the signature:
        1. Get the UMAaas 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: '2023-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 user upload job completes or fails.
        This endpoint should be implemented by clients of the UMAaas API.

        ### Authentication
        The webhook includes a signature in the `X-UMAaas-Signature` header that allows you to verify that the webhook was sent by UMAaas.
        To verify the signature:
        1. Get the UMAaas 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:
                  bulkUserImportJob:
                    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: '2023-08-15T14:32:00Z'
              failedUpload:
                summary: Failed bulk upload
                value:
                  bulkUserImportJob:
                    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: '2023-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 user.
        This endpoint should be implemented by platform clients of the UMAaaS API.

        When a user 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 users 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-UMAaas-Signature` header that allows you to verify that the webhook was sent by UMAaas.
        To verify the signature:
        1. Get the UMAaas 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: '2023-09-01T14:30:00Z'
                    claimedAt: '2023-09-01T15:45:00Z'
                    inviterUma: $inviter@uma.domain
                    inviteeUma: $invitee@uma.domain
                    status: CLAIMED
                    url: https://uma.me/i/019542f5
                  timestamp: '2023-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'
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-UMAaas-Signature
      description: |
        Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by UMAaas.

        To verify the signature:
        1. Get the UMAaas 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:
    AllErrors:
      anyOf:
        - $ref: '#/components/schemas/Error400'
        - $ref: '#/components/schemas/Error401'
        - $ref: '#/components/schemas/Error403'
        - $ref: '#/components/schemas/Error404'
        - $ref: '#/components/schemas/Error409'
        - $ref: '#/components/schemas/Error412'
        - $ref: '#/components/schemas/Error424'
        - $ref: '#/components/schemas/Error500'
        - $ref: '#/components/schemas/Error501'
    UserType:
      type: string
      enum:
        - INDIVIDUAL
        - BUSINESS
      description: Whether the user is an individual or a business entity
      example: INDIVIDUAL
    IndividualUser:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          required:
            - bankAccountInfo
          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'
            bankAccountInfo:
              $ref: '#/components/schemas/UserBankAccountInfo'
    User:
      type: object
      required:
        - umaAddress
        - platformUserId
        - userType
      properties:
        id:
          type: string
          description: System-generated unique identifier
          readOnly: true
          example: User:019542f5-b3e7-1d02-0000-000000000001
        umaAddress:
          type: string
          description: full UMA address
          example: $john.doe@uma.domain.com
        platformUserId:
          type: string
          description: Platform-specific user identifier
          example: 9f84e0c2a72c4fa
        userType:
          $ref: '#/components/schemas/UserType'
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          readOnly: true
          example: '2023-07-21T17:32:28Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          readOnly: true
          example: '2023-07-21T17:32:28Z'
        isDeleted:
          type: boolean
          description: Whether the user is marked as deleted
          example: false
          readOnly: true
      discriminator:
        propertyName: userType
        mapping:
          INDIVIDUAL: '#/components/schemas/IndividualUser'
          BUSINESS: '#/components/schemas/BusinessUser'
    Address:
      type: object
      description: Physical address information
      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
        town:
          type: string
          description: Town/Neighborhood
          example: Hollywood
        city:
          type: string
          description: City
          example: Los Angeles
        state:
          type: string
          description: State/County/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
    ClabeAccountInfo:
      type: object
      required:
        - clabeNumber
        - bankName
      properties:
        clabeNumber:
          type: string
          description: 18-digit CLABE number (Mexican banking standard)
          example: '123456789012345678'
          minLength: 18
          maxLength: 18
          pattern: ^[0-9]{18}$
        bankName:
          type: string
          description: Name of the bank
          example: BBVA Mexico
        accountHolderName:
          type: string
          description: Name of the account holder
          example: John Doe
    UserClabeAccountInfo:
      allOf:
        - $ref: '#/components/schemas/ClabeAccountInfo'
        - $ref: '#/components/schemas/BankAccountBase'
    UsAccountInfo:
      type: object
      required:
        - accountNumber
        - routingNumber
        - accountCategory
      properties:
        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
        accountHolderName:
          type: string
          description: Name of the account holder
          example: John Doe
    BankAccountBase:
      type: object
      required:
        - accountType
      properties:
        platformAccountId:
          type: string
          description: |
            Platform-specific identifier for this bank account. This optional field allows platforms
            to link bank accounts to their internal account systems. The value can be any string
            that helps identify the account in your system (e.g. database IDs, custom references, etc.).

            This field is particularly useful when:
            - Tracking multiple bank accounts for the same user
            - Linking accounts to internal accounting systems
            - Maintaining consistency between UMAaaS and your platform's account records
          example: acc_123456789
        accountType:
          $ref: '#/components/schemas/BankAccountType'
      discriminator:
        propertyName: accountType
        mapping:
          CLABE: '#/components/schemas/UserClabeAccountInfo'
          US_ACCOUNT: '#/components/schemas/UserUsAccountInfo'
          PIX: '#/components/schemas/UserPixAccountInfo'
          IBAN: '#/components/schemas/UserIbanAccountInfo'
          FBO: '#/components/schemas/UserFboAccountInfo'
          UPI: '#/components/schemas/UserUpiAccountInfo'
    UserUsAccountInfo:
      allOf:
        - $ref: '#/components/schemas/UsAccountInfo'
        - $ref: '#/components/schemas/BankAccountBase'
        - type: object
          required:
            - accountHolderName
          properties:
            accountHolderName:
              type: string
              description: Name of the account holder
              example: Jane Doe
    PixAccountInfo:
      type: object
      required:
        - pixKey
        - pixKeyType
      properties:
        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
        bankName:
          type: string
          description: Name of the bank
          example: Nubank
        accountHolderName:
          type: string
          description: Name of the account holder
          example: John Doe
    UserPixAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PixAccountInfo'
        - $ref: '#/components/schemas/BankAccountBase'
    IbanAccountInfo:
      type: object
      required:
        - iban
        - bankName
      properties:
        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
        bankName:
          type: string
          description: Name of the bank
          example: Deutsche Bank
        accountHolderName:
          type: string
          description: Name of the account holder
          example: John Doe
    UserIbanAccountInfo:
      allOf:
        - $ref: '#/components/schemas/IbanAccountInfo'
        - $ref: '#/components/schemas/BankAccountBase'
    UserFboAccountInfo:
      allOf:
        - $ref: '#/components/schemas/BankAccountBase'
        - type: object
          required:
            - currencyCode
          properties:
            currencyCode:
              type: string
              description: Three-letter currency code (ISO 4217)
              example: USD
    UpiAccountInfo:
      type: object
      required:
        - vpa
      properties:
        vpa:
          type: string
          description: Virtual Payment Address for UPI payments
          example: someuser@okbank
        accountHolderName:
          type: string
          description: Name of the account holder
          example: John Doe
    UserUpiAccountInfo:
      allOf:
        - $ref: '#/components/schemas/UpiAccountInfo'
        - $ref: '#/components/schemas/BankAccountBase'
    BankAccountType:
      type: string
      enum:
        - CLABE
        - US_ACCOUNT
        - PIX
        - IBAN
        - FBO
        - UPI
      description: Type of bank account information
    UserBankAccountInfo:
      oneOf:
        - $ref: '#/components/schemas/UserClabeAccountInfo'
        - $ref: '#/components/schemas/UserUsAccountInfo'
        - $ref: '#/components/schemas/UserPixAccountInfo'
        - $ref: '#/components/schemas/UserIbanAccountInfo'
        - $ref: '#/components/schemas/UserFboAccountInfo'
        - $ref: '#/components/schemas/UserUpiAccountInfo'
      discriminator:
        propertyName: accountType
        mapping:
          CLABE: '#/components/schemas/UserClabeAccountInfo'
          US_ACCOUNT: '#/components/schemas/UserUsAccountInfo'
          PIX: '#/components/schemas/UserPixAccountInfo'
          IBAN: '#/components/schemas/UserIbanAccountInfo'
          FBO: '#/components/schemas/UserFboAccountInfo'
          UPI: '#/components/schemas/UserUpiAccountInfo'
    BusinessUser:
      allOf:
        - $ref: '#/components/schemas/User'
        - type: object
          required:
            - bankAccountInfo
          properties:
            address:
              $ref: '#/components/schemas/Address'
            bankAccountInfo:
              $ref: '#/components/schemas/UserBankAccountInfo'
            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
    Error400:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 400
          type: integer
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | INVALID_INPUT | Invalid input provided |
            | MISSING_MANDATORY_USER_INFO | Required user 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
    Error401:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 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:
          enum:
            - 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
    Error409:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 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
    Error501:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 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
    Error404:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 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 | User 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
    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, users and transactions TRANSACT: Can send payments MANAGE: Can manage platform config, api tokens and users'
    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 UMAaaS.
          example: 01947d2284054f890000e63bca4810df
        clientSecret:
          type: string
          description: The secret that should be used to authenticate against UMAaaS 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: '2023-07-21T17:32:28Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2023-07-21T17:32:28Z'
    UserInfoFieldName:
      type: string
      enum:
        - FULL_NAME
        - BIRTH_DATE
        - NATIONALITY
        - PHONE_NUMBER
        - EMAIL
        - POSTAL_ADDRESS
        - TAX_ID
        - REGISTRATION_NUMBER
        - USER_TYPE
        - COUNTRY_OF_RESIDENCE
        - ACCOUNT_IDENTIFIER
        - FI_LEGAL_ENTITY_NAME
        - FI_ADDRESS
        - PURPOSE_OF_PAYMENT
        - ULTIMATE_INSTITUTION_COUNTRY
        - IDENTIFIER
        - BUSINESS_TYPE
      description: Name of a type of field containing info about a platform's user or counterparty user.
      example: FULL_NAME
    CounterpartyFieldDefinition:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/UserInfoFieldName'
        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 users. 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
        umaProviderRequiredUserFields:
          type: array
          items:
            $ref: '#/components/schemas/UserInfoFieldName'
          description: List of user info field names that are required by the underlying UMA provider when creating a user for this currency. These fields must be supplied when creating or updating a user if this currency is intended to be used by that user. If no fields are required, this field is omitted.
          readOnly: true
          example:
            - NATIONALITY
            - BIRTH_DATE
        umaProviderRequiredCounterpartyUserFields:
          type: array
          items:
            $ref: '#/components/schemas/UserInfoFieldName'
          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: Platform:019542f5-b3e7-1d02-0000-000000000003
        umaDomain:
          type: string
          description: UMA domain for this platform
          example: platform.uma.domain
        proxyUmaaasSubdomain:
          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
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          readOnly: true
          example: '2023-06-15T12:30:45Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          readOnly: true
          example: '2023-06-15T12:30:45Z'
    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
    Transaction:
      type: object
      required:
        - id
        - status
        - type
        - senderUmaAddress
        - receiverUmaAddress
        - userId
        - platformUserId
      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'
        senderUmaAddress:
          type: string
          description: UMA address of the payment sender
          example: $sender@external.domain
        receiverUmaAddress:
          type: string
          description: UMA address of the payment recipient
          example: $recipient@uma.domain
        userId:
          type: string
          description: System ID of the user (sender for outgoing, recipient for incoming)
          example: User:019542f5-b3e7-1d02-0000-000000000001
        platformUserId:
          type: string
          description: Platform-specific ID of the user (sender for outgoing, recipient for incoming)
          example: 18d3e5f7b4a9c2
        settledAt:
          type: string
          format: date-time
          description: When the payment was or will be settled
          example: '2023-08-15T14:30:00Z'
        createdAt:
          type: string
          format: date-time
          description: When the transaction was created
          example: '2023-08-15T14:25:18Z'
        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
          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'
    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. "SAT" for satoshis, "USDC" for USDCoin, 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'
    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:
        - umaaasMultiplier
        - umaaasFixedFee
        - umaaasVariableFeeRate
        - umaaasVariableFeeAmount
      properties:
        umaaasMultiplier:
          type: number
          format: double
          description: The underlying multiplier from the mSATS to the receiving currency, including variable fees.
          exclusiveMinimum: 0
          example: 0.925
        umaaasFixedFee:
          type: integer
          format: int64
          description: The fixed fee charged by the UMAaaS product to execute the quote in the smallest unit of the receiving currency (eg. cents).
          minimum: 0
          example: 10
        umaaasVariableFeeRate:
          type: number
          format: double
          description: The variable fee rate charged by the UMAaaS product to execute the quote as a percentage of the receiving currency amount.
          minimum: 0
          example: 0.003
        umaaasVariableFeeAmount:
          type: number
          format: int64
          description: The variable fee amount charged by the UMAaaS product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times umaaasVariableFeeRate.
          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:
            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.
    PaymentClabeAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - $ref: '#/components/schemas/ClabeAccountInfo'
    PaymentBankAccountInfo:
      type: object
      required:
        - accountType
      properties:
        accountType:
          $ref: '#/components/schemas/BankAccountType'
      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'
    PaymentUsAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - $ref: '#/components/schemas/UsAccountInfo'
    PaymentPixAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - $ref: '#/components/schemas/PixAccountInfo'
    PaymentIbanAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - $ref: '#/components/schemas/IbanAccountInfo'
    PaymentFboAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - type: object
          required:
            - paymentUrl
            - paymentMethod
          properties:
            paymentUrl:
              type: string
              format: uri
              description: The url to make request to in order to confirm payment
              example: https://api.umaaas.uma.money/confirm
            paymentMethod:
              type: string
              enum:
                - POST
                - GET
              description: The HTTP method to use for confirming the payment
              example: POST
    PaymentUpiAccountInfo:
      allOf:
        - $ref: '#/components/schemas/PaymentBankAccountInfo'
        - $ref: '#/components/schemas/UpiAccountInfo'
    PaymentInstructions:
      type: object
      required:
        - reference
        - bankAccountInfo
      properties:
        reference:
          type: string
          description: Unique reference code that must be included with the payment to properly credit it
          example: UMA-Q12345-REF
        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
        bankAccountInfo:
          oneOf:
            - $ref: '#/components/schemas/PaymentClabeAccountInfo'
            - $ref: '#/components/schemas/PaymentUsAccountInfo'
            - $ref: '#/components/schemas/PaymentPixAccountInfo'
            - $ref: '#/components/schemas/PaymentIbanAccountInfo'
            - $ref: '#/components/schemas/PaymentFboAccountInfo'
            - $ref: '#/components/schemas/PaymentUpiAccountInfo'
          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'
    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: '2023-08-15T14:30:00Z'
        settledAt:
          type: string
          format: date-time
          description: When the refund was or will be settled
          example: '2023-08-15T14:30:00Z'
    OutgoingRateDetails:
      description: Details about the rate and fees for an outgoing transaction or quote.
      type: object
      required:
        - counterpartyMultiplier
        - counterpartyFixedFee
        - umaaasMultiplier
        - umaaasFixedFee
        - umaaasVariableFeeRate
        - umaaasVariableFeeAmount
      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
        umaaasMultiplier:
          type: number
          format: double
          description: The underlying multiplier from the sending currency to mSATS, including variable fees.
          exclusiveMinimum: 0
          example: 0.925
        umaaasFixedFee:
          type: integer
          format: int64
          description: The fixed fee charged by the UMAaaS product to execute the quote in the smallest unit of the sending currency (eg. cents).
          minimum: 0
          example: 10
        umaaasVariableFeeRate:
          type: number
          format: double
          description: The variable fee rate charged by the UMAaaS product to execute the quote as a percentage of the sending currency amount.
          minimum: 0
          example: 0.003
        umaaasVariableFeeAmount:
          type: number
          format: int64
          description: The variable fee amount charged by the UMAaaS product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times umaaasVariableFeeRate.
          minimum: 0
          example: 30
    OutgoingTransactionFailureReason:
      type: string
      enum:
        - QUOTE_EXPIRED
        - QUOTE_EXECUTION_FAILED
        - LIGHTNING_PAYMENT_FAILED
        - FUNDING_AMOUNT_MISMATCH
        - COUNTERPARTY_POST_TX_FAILED
        - TIMEOUT
        - MANUAL_REFUND
      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.
    CounterpartyDeliveryStatus:
      type: string
      enum:
        - PENDING
        - COMPLETED
        - FAILED
      description: The status of the delivery of the payment from the counterparty to the end recipient. This will only be present if the transaction has passed the `COMPLETED` status.
    OutgoingTransaction:
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          required:
            - sentAmount
            - paymentInstructions
          properties:
            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:
              $ref: '#/components/schemas/PaymentInstructions'
              description: Contains the reference code, banking details, and instructions needed to complete the payment
            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.
            counterpartyDeliveryStatus:
              $ref: '#/components/schemas/CounterpartyDeliveryStatus'
              description: Status of the delivery of the payment. This will only be present if the transaction has passed the `COMPLETED` status.
    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
    Error412:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 412
          type: integer
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | UNSUPPORTED_UMA_VERSION | Counterparty doesn't support UMA as a service UMA version |
          enum:
            - UNSUPPORTED_UMA_VERSIONED
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
    Error424:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 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
    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).
    Quote:
      type: object
      required:
        - quoteId
        - sendingCurrency
        - receivingCurrency
        - totalSendingAmount
        - totalReceivingAmount
        - exchangeRate
        - expiresAt
        - feesIncluded
        - paymentInstructions
        - transactionId
      properties:
        quoteId:
          type: string
          description: Unique identifier for this quote
          example: Quote:019542f5-b3e7-1d02-0000-000000000006
        sendingCurrency:
          $ref: '#/components/schemas/Currency'
        receivingCurrency:
          $ref: '#/components/schemas/Currency'
        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
        expiresAt:
          type: string
          format: date-time
          description: When this quote expires (typically 1-5 minutes after creation)
          example: '2023-09-01T14:30:00Z'
        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
        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
        paymentInstructions:
          $ref: '#/components/schemas/PaymentInstructions'
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
            - EXPIRED
          description: Current status of the quote
          example: PENDING
        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.
    BulkUserImportJob:
      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 users to process
              example: 5000
            processed:
              type: integer
              description: Number of users processed so far
              example: 2500
            successful:
              type: integer
              description: Number of users successfully created
              example: 2450
            failed:
              type: integer
              description: Number of users 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 user 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: '2023-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: '2023-09-01T14:30:00Z'
        claimedAt:
          type: string
          format: date-time
          description: When the invitation was claimed if it has been claimed
          example: '2023-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: '2023-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 user 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.
        inviteeCountryCode:
          type: string
          description: The country of the invitee (ISO 3166-1 alpha-2 code). Only available for CLAIMED invitations when provided by the invitee.
          example: US
    Error403:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          enum:
            - 403
          type: integer
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | FORBIDDEN | Insufficient permissions |
            | USER_NOT_READY | User 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
    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
            requestedReceiverUserInfoFields:
              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 UMAaaS does not already have from initial user 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: '2023-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'
    WebhookType:
      type: string
      enum:
        - INCOMING_PAYMENT
        - OUTGOING_PAYMENT
        - TEST
        - BULK_UPLOAD
        - INVITATION_CLAIMED
      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:
            - bulkUserImportJob
          properties:
            bulkUserImportJob:
              $ref: '#/components/schemas/BulkUserImportJob'
            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
              enum:
                - INVITATION_CLAIMED
              description: Type of webhook event
              example: INVITATION_CLAIMED
    IncomingPaymentWebhookResponse:
      type: object
      properties:
        receiverUserInfo:
          type: object
          additionalProperties: true
          description: Information about the recipient, provided by the platform if requested in the webhook via `requestedReceiverUserInfoFields` 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