openapi: 3.0.1
info:
  description: >-
    The Ripple Collection APIs are used to manage collections, manage payment
    channels, manage partners and settlements.

    ## API Environments

    The Ripple Collection APIs offers the following environments:

    | <div style="width:90px">Environment</div>  | Base URL                     
    | Description                               |

    | ------------------------------------------ | -----------------------------
    | ----------------------------------------- |

    | Sandbox                                    |
    `https://docs.ripple.com/products/collections/_mock/api/collections` |
    Sandbox environment with mock data which does not require auth.|

    | UAT                                       | `https://api.test.ripple.com`
    | UAT environment with simulated transactions. |

    | Production                                 | `https://api.ripple.com`     
    | Production environment                    |


    For guides on API authentication, idempotency, and webhook verification, see
    the sidebar. 
  title: Ripple Collections
  version: 1.0.0
servers:
  - url: https://api.test.ripple.com
  - url: https://api.ripple.com
tags:
  - name: Authentication
    description: Endpoints for authentication
  - name: Accounts
    description: Endpoints for managing payment accounts
  - name: Collection Links
    description: >-
      Endpoints for managing one-time collection links with account-based
      routing
  - name: Collection Channels
    description: >-
      Endpoints for managing persistent collection channels with account-based
      routing
  - name: Partners
    description: Endpoints for managing partners who can transact
  - name: Settlements
    description: Endpoints for managing settlements
  - name: Transactions
    description: >-
      Endpoints for viewing transactions across collection links and channels
      with account-based routing
  - name: Webhooks
    description: Endpoints for managing webhook registrations
paths:
  /v2/oauth/token:
    post:
      tags:
        - Authentication
      operationId: authenticate
      summary: Request an access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
      responses:
        '200':
          description: >-
            Returns the authentication response object that includes the token,
            type, scopes, and expiry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              example:
                error_description: 'Missing required parameter: grant_type'
                error: invalid_request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              example:
                error_description: Unauthorized
                error: access_denied
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthErrorResponse'
              example:
                error_description: 'Service not enabled within domain: <wrong:domain>'
      description: >
        Request an access token for authentication with Ripple APIs.


        You need to request a token for the environment you want to authenticate
        with.


        **Note**: The length of the access token isn't fixed, hence it can vary.
        Avoid validating tokens based on character length.


        **Tutorials**


        * Learn how to [Request an access
        token](../../tutorials/request-an-access-token/).


        #### Environments


        | Environment | Domain | Description |

        | --- | --- | --- |

        | UAT | `api.test.ripple.com` | UAT environment with simulated
        transactions. |

        | Production | `api.ripple.com` | Production environment |
  /v2/oauth/token/test:
    get:
      tags:
        - Authentication
      operationId: testAuthToken
      security:
        - Bearer: []
      summary: Test access token
      description: >-
        Test if an access token can be used for authentication with Ripple APIs
        and how much time remains on it.
      responses:
        '200':
          description: >-
            If a valid bearer token is supplied, the time remaining before the
            token expires is returned.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ValidateTokenResponse'
                type: array
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                type: string
              example: Invalid Request parameters [Invalid bearer authentication token]
        '401':
          description: Unauthorized
  /v1/collections/accounts:
    get:
      tags:
        - Accounts
      summary: List accounts
      description: Retrieves a list of accounts, filterable by query parameters.
      operationId: listAccountsV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter accounts by specific account identifier
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: account_owner_id
          in: query
          description: Filter accounts by account owner identifier
          schema:
            type: string
            format: uuid
            example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
        - name: currency
          in: query
          description: Filter accounts by currency
          schema:
            type: string
          example: USD
        - name: type
          in: query
          description: Filter accounts by type
          schema:
            $ref: '#/components/schemas/AccountType'
          example: FIAT
        - name: status
          in: query
          description: Filter accounts by status
          schema:
            $ref: '#/components/schemas/AccountStatus'
          example: ACTIVE
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: A list of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
              examples:
                default:
                  summary: Example account list response
                  value:
                    content:
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                        currency: USD
                        type: FIAT
                        rails:
                          - FEDWIRE
                          - ACH
                          - RTP
                        balances:
                          available:
                            amount: '1250.50'
                          pending:
                            inbound:
                              amount: '50.00'
                            outbound:
                              amount: '25.00'
                        ownership_level: PARTNER
                        status: ACTIVE
                        created_at: '2025-09-18T22:54:00.542Z'
                        updated_at: '2025-09-18T22:54:00.542Z'
                      - id: 250d6dc5-382f-4750-8657-0780be594d68
                        account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                        currency: BRL
                        type: FIAT
                        rails:
                          - PIX
                        balances:
                          available:
                            amount: '0.00'
                          pending:
                            inbound:
                              amount: '0.00'
                            outbound:
                              amount: '0.00'
                        ownership_level: PARTNER
                        status: ACTIVE
                        created_at: '2025-09-18T22:54:00.542Z'
                        updated_at: '2025-09-18T22:54:00.542Z'
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                        currency: USDC
                        type: CRYPTO
                        rails:
                          - BLOCKCHAIN
                        balances:
                          available:
                            amount: '0.00'
                          pending:
                            inbound:
                              amount: '0.00'
                            outbound:
                              amount: '0.00'
                        ownership_level: PARTNER
                        status: ACTIVE
                        created_at: '2025-09-18T22:54:00.542Z'
                        updated_at: '2025-09-18T22:54:00.542Z'
                    page:
                      page: 1
                      size: 10
                      total_elements: 3
                      total_pages: 1
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Accounts
      summary: Create an account
      description: >
        Creates a new payment account for a beneficiary partner. The account
        type (CRYPTO or FIAT)

        is determined by the currency specified. Account creation is subject to
        the beneficiary's

        partner eligibility.
      operationId: createAccountV1
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
            examples:
              crypto_account:
                summary: Example crypto account creation
                value:
                  beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                  currency: USDC
              usd_fiat_account:
                summary: Example USD fiat account creation
                value:
                  beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                  currency: USD
              brl_fiat_account:
                summary: Example BRL fiat account creation
                value:
                  beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                  currency: BRL
      responses:
        '201':
          description: Account created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              examples:
                customer_usd_fiat_account:
                  summary: Example customer USD fiat account response
                  value:
                    id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    account_owner_id: 87a6b830-1bbe-409c-9bff-9cf12bed774f
                    currency: USD
                    type: FIAT
                    rails:
                      - FEDWIRE
                      - ACH
                      - RTP
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: CUSTOMER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                customer_brl_fiat_account:
                  summary: Example customer BRL fiat account response
                  value:
                    id: 250d6dc5-382f-4750-8657-0780be594d68
                    account_owner_id: 87a6b830-1bbe-409c-9bff-9cf12bed774f
                    currency: BRL
                    type: FIAT
                    rails:
                      - PIX
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: CUSTOMER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                customer_usdc_crypto_account:
                  summary: Example customer USDC crypto account response
                  value:
                    id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    account_owner_id: 87a6b830-1bbe-409c-9bff-9cf12bed774f
                    currency: USDC
                    type: CRYPTO
                    rails:
                      - BLOCKCHAIN
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: CUSTOMER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                crypto_account:
                  summary: Example crypto account response
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                    currency: USDC
                    type: CRYPTO
                    rails:
                      - BLOCKCHAIN
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: PARTNER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                usd_fiat_account:
                  summary: Example USD fiat account response
                  value:
                    id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                    currency: USD
                    type: FIAT
                    rails:
                      - FEDWIRE
                      - ACH
                      - RTP
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: PARTNER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                brl_fiat_account:
                  summary: Example BRL fiat account response
                  value:
                    id: 250d6dc5-382f-4750-8657-0780be594d68
                    account_owner_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                    currency: BRL
                    type: FIAT
                    rails:
                      - PIX
                    balances:
                      available:
                        amount: '0.00'
                      pending:
                        inbound:
                          amount: '0.00'
                        outbound:
                          amount: '0.00'
                    ownership_level: PARTNER
                    status: ACTIVE
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Partner access does not allow this account type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/accounts/{account_id}:
    get:
      tags:
        - Accounts
      summary: Get account by ID
      description: Retrieves the details of a specific account by its ID.
      operationId: getAccountByIdV1
      security:
        - Bearer: []
      parameters:
        - name: account_id
          in: path
          required: true
          description: Unique identifier of the account to retrieve
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/partners:
    get:
      tags:
        - Partners
      summary: List partners
      description: Retrieves a list of partners, filterable by ID or type.
      operationId: listPartnersV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter partners by specific partner ID
          schema:
            type: string
            format: uuid
            example: 0c5479ff-3772-4123-b2b7-e679e71eb570
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after partner was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before partner was created
          example: '2025-06-17T12:00:00Z'
        - name: type
          in: query
          description: Filter partners by type
          schema:
            type: string
            $ref: '#/components/schemas/PartnerType'
        - name: status
          in: query
          description: Filter partners by status
          schema:
            type: string
            $ref: '#/components/schemas/PartnerStatus'
        - name: external_reference_id
          in: query
          schema:
            type: string
            description: External reference id for partner
          example: Ref-123
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: A list of partners.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/PartnerV1'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
        '400':
          description: >-
            Bad Request - Invalid input parameters or invalid field partner for
            business or individual partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Partners
      summary: Create a partner
      description: This API allows users to add new parties who can transact.
      operationId: createPartnerV1
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartnerRequest'
      responses:
        '201':
          description: Partner created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/partners/{partner_id}:
    get:
      tags:
        - Partners
      summary: Get partner by ID
      description: This API allows users to retrieve a specific partner by their ID.
      operationId: getPartnerByIdV1
      security:
        - Bearer: []
      parameters:
        - name: partner_id
          in: path
          required: true
          description: Unique identifier of the partner to retrieve
          schema:
            type: string
            format: uuid
            example: 0c5479ff-3772-4123-b2b7-e679e71eb570
        - name: external_reference_id
          in: query
          schema:
            type: string
            description: External reference id for partner
          example: Ref-123
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Partner does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Partners
      summary: Update a partner
      description: API to update a partner to use in collections API.
      operationId: updatePartnerV1
      security:
        - Bearer: []
      parameters:
        - name: partner_id
          in: path
          required: true
          description: Unique identifier of the partner to update
          schema:
            type: string
            format: uuid
            example: 0c5479ff-3772-4123-b2b7-e679e71eb570
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePartnerRequest'
      responses:
        '200':
          description: Partner updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Partner does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/settlements:
    get:
      tags:
        - Settlements
      summary: List settlements
      description: >-
        API to fetch first party payouts (settlements) with enhanced v1 response
        format.
      operationId: listSettlementsV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter settlements by specific settlement ID
          schema:
            type: string
            format: uuid
            example: 63dd59dd-88be-41a2-a246-2f6724209422
        - name: type
          in: query
          schema:
            $ref: '#/components/schemas/SettlementType'
          description: Settlement type
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/SettlementStatus'
          description: Settlement status
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after settlement was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before settlement was created
          example: '2025-06-17T12:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of settlements per page
          example: 10
      responses:
        '200':
          description: A list of settlements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/SettlementV1'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Settlements
      summary: Create a settlement
      description: API to initiate a first party payout (settlement to our customer).
      operationId: createSettlementV1
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSettlementRequestV1'
      responses:
        '201':
          description: Settlement created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/settlements/{settlement_id}:
    get:
      tags:
        - Settlements
      summary: Get settlement by ID
      description: >-
        API to fetch a first party payout (settlement to our customer) with
        enhanced v1 response format.
      operationId: getSettlementByIdV1
      security:
        - Bearer: []
      parameters:
        - name: settlement_id
          in: path
          required: true
          description: Unique identifier of the settlement to retrieve
          schema:
            type: string
            format: uuid
            example: 63dd59dd-88be-41a2-a246-2f6724209422
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Settlement does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/channels:
    get:
      tags:
        - Collection Channels
      summary: List channels
      description: >-
        Retrieves a list of channels using account-based routing, filterable by
        query parameters.
      operationId: listChannelsV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter channels by specific channel identifier
          schema:
            type: string
            format: uuid
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: payer_id
          in: query
          description: Filter channels by payer identifier
          schema:
            type: string
            format: uuid
            example: e471b938-98ad-45e4-b144-53a556ea047d
        - name: account_id
          in: query
          description: Filter channels by account identifier
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: beneficiary_id
          in: query
          description: Filter channels by beneficiary identifier
          schema:
            type: string
            format: uuid
            example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
        - name: status
          in: query
          description: Filter channels by status
          schema:
            $ref: '#/components/schemas/ChannelStatus'
          example: ACTIVE
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after channel was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before channel was created
          example: '2025-06-17T12:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: A list of channels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChannelV1'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
              examples:
                default:
                  summary: Example channel list response
                  value:
                    content:
                      - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        payer:
                          id: e471b938-98ad-45e4-b144-53a556ea047d
                          name: Nigerian Imports Ltd.
                          email: nigerian@imports.com
                        beneficiary:
                          id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                          name: Hong Kong Exports Ltd.
                          email: hongkong@exports.com
                        account:
                          id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                          beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                          currency: USDC
                          type: CRYPTO
                        payment_methods:
                          - type: BLOCKCHAIN
                            network: ETHEREUM
                            address: '0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5'
                            currency: USDC
                        payment_link: >-
                          https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6
                        transactions: []
                        status: ACTIVE
                        reason: null
                        created_at: '2025-09-18T22:54:00.542Z'
                        updated_at: '2025-09-18T22:54:00.542Z'
                      - id: cb34b0e3-d20d-4a7c-9ad7-b461d7991555
                        payer:
                          id: e471b938-98ad-45e4-b144-53a556ea047d
                          name: Nigerian Imports Ltd.
                          email: nigerian@imports.com
                        beneficiary:
                          id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                          name: Hong Kong Exports Ltd.
                          email: hongkong@exports.com
                        account:
                          id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                          beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                          currency: USD
                          type: FIAT
                        payment_methods:
                          - type: FEDWIRE
                            account_number: '1234567890'
                            routing_number: '021000021'
                            swift_code: CHASUS33
                            memo: CH-cb34b0e3
                          - type: ACH
                            account_number: '1234567890'
                            routing_number: '021000021'
                            memo: CH-cb34b0e3
                        payment_link: >-
                          https://collections.ripplenet.com/pay/channel/cb34b0e3-d20d-4a7c-9ad7-b461d7991555
                        transactions: []
                        status: ACTIVE
                        reason: null
                        created_at: '2025-09-18T22:54:00.542Z'
                        updated_at: '2025-09-18T22:54:00.542Z'
                    page:
                      page: 1
                      size: 10
                      total_elements: 2
                      total_pages: 1
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Collection Channels
      summary: Create a channel
      description: >
        Creates a new payment channel using account-based routing. The channel
        is associated

        with an account which determines the available payment rails (crypto
        networks or fiat

        rails) based on the account's currency.
      operationId: createChannelV1
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChannelRequestV1'
            examples:
              default:
                summary: Example channel creation request
                value:
                  payer_id: e471b938-98ad-45e4-b144-53a556ea047d
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '201':
          description: Channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelV1'
              examples:
                crypto_channel:
                  summary: Example crypto channel response
                  value:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: USDC
                      type: CRYPTO
                    payment_methods:
                      - type: BLOCKCHAIN
                        network: ETHEREUM
                        address: '0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5'
                        currency: USDC
                      - type: BLOCKCHAIN
                        network: SOLANA
                        address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
                        currency: USDC
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                fiat_channel:
                  summary: Example fiat channel response
                  value:
                    id: cb34b0e3-d20d-4a7c-9ad7-b461d7991555
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: USD
                      type: FIAT
                    payment_methods:
                      - type: FEDWIRE
                        account_number: '1234567890'
                        routing_number: '021000021'
                        swift_code: CHASUS33
                        memo: CH-cb34b0e3
                      - type: ACH
                        account_number: '1234567890'
                        routing_number: '021000021'
                        memo: CH-cb34b0e3
                      - type: RTP
                        account_number: '1234567890'
                        routing_number: '021000021'
                        memo: CH-cb34b0e3
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/4gb96g75-6828-5673-c4gd-3d074g77bgb7
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                brl_fiat_channel:
                  summary: Example BRL fiat channel response with PIX
                  value:
                    id: d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Brazilian Imports Ltd.
                      email: brazil@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: 250d6dc5-382f-4750-8657-0780be594d68
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: BRL
                      type: FIAT
                    payment_methods:
                      - type: PIX
                        pix_key: payments@hongkongexports.com
                        pix_key_type: EMAIL
                        beneficiary_name: Hong Kong Exports Ltd.
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Account type not allowed for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Account or payer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/channels/{channel_id}:
    get:
      tags:
        - Collection Channels
      summary: Get channel details
      description: >-
        Retrieves the details of a specific channel by its ID using
        account-based routing.
      operationId: getChannelByIdV1
      security:
        - Bearer: []
      parameters:
        - name: channel_id
          in: path
          required: true
          description: Unique identifier of the channel to retrieve
          schema:
            type: string
            format: uuid
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelV1'
              examples:
                crypto_channel:
                  summary: Example crypto channel response
                  value:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: USDC
                      type: CRYPTO
                    payment_methods:
                      - type: BLOCKCHAIN
                        network: ETHEREUM
                        address: '0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5'
                        currency: USDC
                      - type: BLOCKCHAIN
                        network: SOLANA
                        address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
                        currency: USDC
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                fiat_channel:
                  summary: Example fiat channel response
                  value:
                    id: cb34b0e3-d20d-4a7c-9ad7-b461d7991555
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: USD
                      type: FIAT
                    payment_methods:
                      - type: FEDWIRE
                        account_number: '1234567890'
                        routing_number: '021000021'
                        swift_code: CHASUS33
                        memo: CH-cb34b0e3
                      - type: ACH
                        account_number: '1234567890'
                        routing_number: '021000021'
                        memo: CH-cb34b0e3
                      - type: RTP
                        account_number: '1234567890'
                        routing_number: '021000021'
                        memo: CH-cb34b0e3
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/cb34b0e3-d20d-4a7c-9ad7-b461d7991555
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
                brl_fiat_channel:
                  summary: Example BRL fiat channel response with PIX
                  value:
                    id: d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Brazilian Imports Ltd.
                      email: brazil@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    account:
                      id: 250d6dc5-382f-4750-8657-0780be594d68
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: BRL
                      type: FIAT
                    payment_methods:
                      - type: PIX
                        pix_key: payments@hongkongexports.com
                        pix_key_type: EMAIL
                        beneficiary_name: Hong Kong Exports Ltd.
                    payment_link: >-
                      https://collections.ripplenet.com/pay/channel/d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a
                    transactions: []
                    status: ACTIVE
                    reason: null
                    created_at: '2025-09-18T22:54:00.542Z'
                    updated_at: '2025-09-18T22:54:00.542Z'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Channel does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/links:
    get:
      tags:
        - Collection Links
      summary: List collections
      description: >-
        Retrieves a list of collections using account-based routing, filterable
        by query parameters.
      operationId: listCollectionsV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter collections by specific collection identifier
          schema:
            type: string
            format: uuid
            example: e8d43598-107d-4694-9fb2-934e7484c3d4
        - name: payer_id
          in: query
          description: Filter collections by payer identifier
          schema:
            type: string
            format: uuid
            example: 0c5479ff-3772-4123-b2b7-e679e71eb570
        - name: account_id
          in: query
          description: Filter collections by account identifier
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: beneficiary_id
          in: query
          description: Filter collections by beneficiary identifier
          schema:
            type: string
            format: uuid
            example: 01467076-8bb0-41c1-ad54-5751dd4a9e80
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after collection was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before collection was created
          example: '2025-06-17T12:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: A list of collections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionV1'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Collection Links
      summary: Create a collection
      description: >
        Creates a new payment link for a collection using account-based routing.
        The collection

        is associated with an account which determines the available payment
        rails and currency.

        The amount is denominated in the account's currency.
      operationId: createCollectionV1
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequestV1'
            examples:
              example_with_excluded_fee:
                summary: Example for EXCLUDED fee_mode
                value:
                  payer_id: 0c5479ff-3772-4123-b2b7-e679e71eb570
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  amount: '800.00'
                  fee_mode: EXCLUDED
                  reference_id: INV-2025-009
                  description: 'Payment for Order #2668'
                  link_expiry: 172800
                  return_url: https://example.com/payment/completion
              example_with_included_fee:
                summary: Example for INCLUDED fee_mode
                value:
                  payer_id: 0c5479ff-3772-4123-b2b7-e679e71eb570
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  amount: '800.00'
                  fee_mode: INCLUDED
                  reference_id: INV-2025-009
                  description: 'Payment for Order #2668'
                  link_expiry: 172800
                  return_url: https://example.com/payment/completion
      responses:
        '201':
          description: Collection Created Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionV1'
              examples:
                default:
                  summary: Example collection response
                  value:
                    id: e8d43598-107d-4694-9fb2-934e7484c3d4
                    payer:
                      id: 0c5479ff-3772-4123-b2b7-e679e71eb570
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    reference_id: INV-2025-009
                    account:
                      id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      beneficiary_id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      currency: USDC
                      type: CRYPTO
                    gross_amount: '808.00'
                    net_amount: '800.00'
                    fee_mode: EXCLUDED
                    fee: '8.00'
                    amount_remaining: '808.00'
                    description: 'Payment for Order #2668'
                    link_expiry: 172800
                    return_url: https://example.com/payment/completion
                    expires_at: '2025-06-30T23:59:59Z'
                    transactions: []
                    payment_link: https://collections.ripple.com/link/pay/384c5f9b
                    status: CREATED
                    reason: null
                    created_at: '2025-06-17T12:00:00Z'
                    updated_at: '2025-06-17T12:30:00Z'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Account type not allowed for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Account or payer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/links/{collection_id}:
    get:
      tags:
        - Collection Links
      summary: Get collection details
      description: >-
        Retrieves the details of a specific collection by its ID using
        account-based routing.
      operationId: getCollectionByIdV1
      security:
        - Bearer: []
      parameters:
        - name: collection_id
          in: path
          required: true
          description: Unique identifier of the collection to retrieve
          schema:
            type: string
            format: uuid
            example: e8d43598-107d-4694-9fb2-934e7484c3d4
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionV1'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Collection does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/transactions:
    get:
      tags:
        - Transactions
      summary: List Transactions
      description: >-
        API to fetch transactions across collection links or channels using
        account-based routing.
      operationId: listTransactionsV1
      security:
        - Bearer: []
      parameters:
        - name: id
          in: query
          description: Filter transactions by specific transaction ID
          schema:
            type: string
            format: uuid
            example: 63dd59dd-88be-41a2-a246-2f6724209422
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/TransactionStatus'
          description: Transaction status
        - name: payer_id
          in: query
          description: Filter transactions by payer identifier
          schema:
            type: string
            format: uuid
            example: e471b938-98ad-45e4-b144-53a556ea047d
        - name: beneficiary_id
          in: query
          description: Filter transactions by beneficiary identifier
          schema:
            type: string
            format: uuid
            example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
        - name: account_id
          in: query
          description: Filter transactions by account identifier
          schema:
            type: string
            format: uuid
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: currency
          in: query
          description: Filter transactions by transaction currency
          schema:
            type: string
          example: USDT
        - name: network
          in: query
          description: Filter transactions by transaction network
          schema:
            type: string
            $ref: '#/components/schemas/Network'
          example: ETHEREUM
        - name: wallet_address
          in: query
          description: Filter transactions by wallet address
          schema:
            type: string
          example: '0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5'
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after transaction was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before transaction was created
          example: '2025-06-17T12:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionV1'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
              examples:
                default:
                  summary: Example transaction list response
                  value:
                    content:
                      - id: 487ba009-56cf-4ad9-8b5c-045e27893e00
                        parent_id: 22a0337b-8e62-449c-91ca-a0f830c55733
                        account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        settlement_id: 9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e
                        payer:
                          id: 0c5479ff-3772-4123-b2b7-e679e71eb570
                          name: Nigerian Imports Ltd.
                          email: nigerian@imports.com
                        beneficiary:
                          id: 01467076-8bb0-41c1-ad54-5751dd4a9e80
                          name: Hong Kong Exports Ltd.
                          email: hongkong@exports.com
                        payment_amount:
                          value: '50.00000000'
                          asset: USDT
                        account_equivalent:
                          gross_amount:
                            value: '50.00'
                            currency: USD
                          fee_amount:
                            value: '0.50'
                            currency: USD
                          net_amount:
                            value: '49.50'
                            currency: USD
                        market_rate:
                          base: USDT
                          counter: USD
                          rate: '1.00'
                        exchange_rate:
                          base: USDT
                          counter: USD
                          rate: '0.99'
                        source_payment_method:
                          type: BLOCKCHAIN
                          network: ETHEREUM
                          transaction_hash: >-
                            0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u
                          block_id: >-
                            0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85
                          source_address: '0x880f622a1933ACf82bFC5e630c9ab7f18eF47809'
                          destination_address: '0x02937b288b588058533C48b18EdFDdd76A324D6'
                          gas_fee:
                            value: '0.0045'
                            asset: ETH
                        status: COMPLETED
                        transaction_processed_date: '2025-06-17T12:20:00Z'
                        date_created: 1566203005000
                        date_confirmed: 1566203005000
                    page:
                      page: 1
                      size: 10
                      total_elements: 1
                      total_pages: 1
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      summary: Get transaction by ID
      description: >-
        API to fetch a transaction (payment from a payer to beneficiary) using
        account-based routing.
      operationId: getTransactionByIdV1
      security:
        - Bearer: []
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: Unique identifier of the transaction to retrieve
          schema:
            type: string
            format: uuid
            example: 487ba009-56cf-4ad9-8b5c-045e27893e00
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionV1'
              examples:
                blockchain_transaction:
                  summary: Example blockchain transaction response
                  value:
                    id: 487ba009-56cf-4ad9-8b5c-045e27893e00
                    parent_id: 22a0337b-8e62-449c-91ca-a0f830c55733
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    settlement_id: 9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e
                    payer:
                      id: 0c5479ff-3772-4123-b2b7-e679e71eb570
                      name: Nigerian Imports Ltd.
                      email: nigerian@imports.com
                    beneficiary:
                      id: 01467076-8bb0-41c1-ad54-5751dd4a9e80
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    payment_amount:
                      value: '50.00000000'
                      asset: USDT
                    account_equivalent:
                      gross_amount:
                        value: '50.00'
                        currency: USD
                      fee_amount:
                        value: '0.50'
                        currency: USD
                      net_amount:
                        value: '49.50'
                        currency: USD
                    market_rate:
                      base: USDT
                      counter: USD
                      rate: '1.00'
                    exchange_rate:
                      base: USDT
                      counter: USD
                      rate: '0.99'
                    source_payment_method:
                      type: BLOCKCHAIN
                      network: ETHEREUM
                      transaction_hash: 0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u
                      block_id: >-
                        0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85
                      source_address: '0x880f622a1933ACf82bFC5e630c9ab7f18eF47809'
                      destination_address: '0x02937b288b588058533C48b18EdFDdd76A324D6'
                      gas_fee:
                        value: '0.0045'
                        asset: ETH
                    status: COMPLETED
                    transaction_processed_date: '2025-06-17T12:20:00Z'
                    date_created: 1566203005000
                    date_confirmed: 1566203005000
                fiat_transaction:
                  summary: Example fiat (PIX) transaction response
                  value:
                    id: 63dd59dd-88be-41a2-a246-2f6724209422
                    parent_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    account_id: 250d6dc5-382f-4750-8657-0780be594d68
                    settlement_id: null
                    payer:
                      id: e471b938-98ad-45e4-b144-53a556ea047d
                      name: Brazilian Imports Ltd.
                      email: brazil@imports.com
                    beneficiary:
                      id: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
                      name: Hong Kong Exports Ltd.
                      email: hongkong@exports.com
                    payment_amount:
                      value: '1000.00'
                      asset: BRL
                    account_equivalent:
                      gross_amount:
                        value: '1000.00'
                        currency: BRL
                      fee_amount:
                        value: '10.00'
                        currency: BRL
                      net_amount:
                        value: '990.00'
                        currency: BRL
                    market_rate:
                      base: BRL
                      counter: BRL
                      rate: '1.00'
                    exchange_rate:
                      base: BRL
                      counter: BRL
                      rate: '1.00'
                    source_payment_method:
                      type: PIX
                      pix_key: '12345678901'
                      pix_key_type: CPF
                      sender_name: João Silva
                    status: COMPLETED
                    transaction_processed_date: '2025-06-17T14:30:00Z'
                    date_created: 1566203005000
                    date_confirmed: 1566203005000
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Transaction does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks
      operationId: listWebhooks
      security:
        - Bearer: []
      parameters:
        - name: event_type
          in: query
          required: true
          description: Unique identifier event type to filter webhooks
          schema:
            type: string
            $ref: '#/components/schemas/EventType'
        - name: since
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp after webhook was created
          example: '2025-06-17T12:00:00Z'
        - name: until
          in: query
          schema:
            type: string
            format: date-time
            description: ISO 8601 timestamp before webhook was created
          example: '2025-06-17T12:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (starts at 1)
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Page size (items per page)
          example: 10
      responses:
        '200':
          description: List of webhooks for the customer and page requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookResponse'
                  page:
                    $ref: '#/components/schemas/PageMetadata'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Webhooks
      summary: Create webhooks
      description: Creates one webhook per event type supplied.
      operationId: createWebhooks
      security:
        - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
            examples:
              create:
                value:
                  callback_url: https://webhook.partner.example/webhooks
                  event_types:
                    - WALLET_ADDRESS_CREATED
                    - SETTLEMENT_COMPLETED
      responses:
        '201':
          description: Webhooks created (one per event type)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookResponse'
              examples:
                created:
                  value:
                    - id: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
                      event_type: WALLET_ADDRESS_CREATED
                      callback_url: https://webhook.partner.example/webhooks
                      signature_verification_key: 9abc1234...
                    - id: 1c9fe6fd-1dd8-4e9a-8de2-7f4c89b4d210
                      event_type: SETTLEMENT_COMPLETED
                      callback_url: https://webhook.partner.example/webhooks
                      signature_verification_key: 1def5678...
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/collections/webhooks/{webhook_id}:
    get:
      tags:
        - Webhooks
      summary: Get a webhook
      operationId: getWebhook
      security:
        - Bearer: []
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: Unique identifier of the webhook to retrieve
          schema:
            type: string
            format: uuid
            example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
      responses:
        '200':
          description: Webhook found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                webhook:
                  value:
                    id: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
                    event_type: WALLET_ADDRESS_CREATED
                    callback_url: https://webhook.partner.example/webhooks
                    signature_verification_key: >-
                      04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Webhook does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Webhooks
      summary: Update a webhook
      operationId: updateWebhook
      security:
        - Bearer: []
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: Unique identifier of the webhook to update
          schema:
            type: string
            format: uuid
            example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Updated webhook id
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                updated:
                  value:
                    id: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
                    event_type: WALLET_ADDRESS_CREATED
                    callback_url: https://webhook-updated.partner.example/webhooks
                    signature_verification_key: 1dec2311...
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Webhook does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Webhooks
      summary: Delete a webhook
      operationId: deleteWebhook
      security:
        - Bearer: []
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: Unique identifier of the webhook to retrieve
          schema:
            type: string
            format: uuid
            example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
      responses:
        '200':
          description: Deleted webhook id
          content:
            application/json:
              schema:
                type: string
                format: uuid
              examples:
                deleted:
                  value: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Webhook does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    AuthenticationRequest:
      description: The authentication request.
      properties:
        client_id:
          type: string
          description: The client ID associated with a specific set of API credentials.
          example: '{YOUR_CLIENT_ID}'
        client_secret:
          type: string
          description: The client secret associated with a specific set of API credentials.
          example: '{YOUR_CLIENT_SECRET}'
        audience:
          type: string
          description: >
            The value of the `audience` field is based on
            [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) syntax.


            **Format**:
            `urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}`


            * The first component is `urn:ripplenetxcurrent-`.

            * The second component refers to the environment you want to access.

            * The third component is your tenant ID. Ripple integration
            engineers provide this component during training.


            | Environment | Environment string | Description |

            | --- | --- | --- |

            | UAT | `uat` | UAT environment with simulated transactions. |

            | Production | `prod` | Production environment for Ripple's internal
            services. |


            **Example**: `urn:ripplexcurrent-uat:{YOUR_TENANT_ID}`
          example: urn:ripplexcurrent-uat:{YOUR_TENANT_ID}
        grant_type:
          type: string
          description: >-
            Set the grant-type for this client credentials request. This must be
            set to `client_credentials`.
          enum:
            - client_credentials
          example: client_credentials
      required:
        - client_id
        - client_secret
        - audience
        - grant_type
      type: object
    AuthenticationResponse:
      description: >-
        The authentication response object that includes the token, type,
        scopes, and expiry.
      properties:
        access_token:
          type: string
          description: The bearer token you use when authenticating with a Ripple API.
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ
        scope:
          type: string
          description: List of scopes applied to your `access_token`.
        expires_in:
          type: integer
          format: int64
          description: >-
            How long your `access_token` is valid. You need to request a new
            token when it expires.
          example: 3600
        token_type:
          type: string
          description: The type of token. Ripple APIs use `Bearer` auth tokens.
          example: Bearer
      type: object
    ValidateTokenResponse:
      description: >-
        The response object indicating a token's validity and the time remaining
        on it
      properties:
        message:
          type: string
          example: token_ok
        seconds_to_expiry:
          type: integer
          format: int64
          description: Remaining time in seconds before the tested token expires.
          example: 3600
    CreatePartnerRequest:
      type: object
      description: Request payload for creating a new partner
      required:
        - name
        - email
      properties:
        name:
          type: string
          description: Full name of the partner organization or individual
          example: Nigerian Imports Ltd.
        email:
          type: string
          description: Email address for partner communications
          format: email
          example: nigerian@imports.com
        external_reference_id:
          type: string
          description: External reference id for partner
          example: Ref-123
        data:
          $ref: '#/components/schemas/PartnerMetadata'
          example:
            type: BUSINESS
            legal_entity: Nigerian Imports Ltd.
            registration_number: RC-123456-NGR
            registration_type: AIIN
            country: NG
            city: Lagos Island
            postal_code: '10010'
            address: 15 Marina Street
            address_line_2: Suite 200
    UpdatePartnerRequest:
      type: object
      description: Request payload for updating an existing partner
      properties:
        name:
          type: string
          description: Full name of the partner organization or individual
          example: Nigerian Imports Ltd.
        email:
          type: string
          description: Email address for partner communications
          format: email
          example: nigerian@imports.com
        external_reference_id:
          type: string
          description: External reference id for partner
          example: Ref-123
        data:
          $ref: '#/components/schemas/PartnerMetadata'
          example:
            type: BUSINESS
            legal_entity: Nigerian Imports Ltd.
            registration_number: RC-123456-NGR
            registration_type: AIIN
            country: NG
            city: Lagos Island
            postal_code: '10010'
            address: 15 Marina Street
            address_line_2: Suite 200
    PartnerV1:
      type: object
      description: Partner response
      required:
        - id
        - name
        - email
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the partner
          readOnly: true
          example: 0c5479ff-3772-4123-b2b7-e679e71eb570
        name:
          type: string
          description: Full name of the partner organization or individual
          example: Nigerian Imports Ltd.
        email:
          type: string
          description: Email address for partner communications
          format: email
          example: nigerian@imports.com
        external_reference_id:
          type: string
          description: External reference id for partner
          example: Ref-123
        data:
          $ref: '#/components/schemas/PartnerMetadata'
          example:
            type: BUSINESS
            legal_entity: Nigerian Imports Ltd.
            registration_number: RC-123456-NGR
            registration_type: AIIN
            country: NG
            city: Lagos Island
            postal_code: '10010'
            address: 15 Marina Street
            address_line_2: Suite 200
        status:
          type: string
          description: Current status of the partner
          $ref: '#/components/schemas/PartnerStatus'
          example: PENDING
        reason:
          type: string
          nullable: true
          description: Reason for current status (if applicable)
          example: null
        created_at:
          type: string
          format: date-time
          description: Timestamp when the partner was created
          readOnly: true
          example: '2025-09-18T22:54:00.542Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the partner was last updated
          readOnly: true
          example: '2025-09-18T23:54:00.542Z'
    PartnerType:
      type: string
      description: Partner type
      enum:
        - BUSINESS
        - INDIVIDUAL
      x-enum-descriptions:
        BUSINESS: Partner is a business entity
        INDIVIDUAL: Partner is an individual
      example: BUSINESS
    PartnerMetadata:
      type: object
      discriminator:
        propertyName: type
        mapping:
          BUSINESS: '#/components/schemas/BusinessMetadata'
          INDIVIDUAL: '#/components/schemas/IndividualMetadata'
      oneOf:
        - $ref: '#/components/schemas/BusinessMetadata'
        - $ref: '#/components/schemas/IndividualMetadata'
    BusinessMetadata:
      type: object
      description: Metadata specific to business partners
      required:
        - type
        - legal_entity
        - registration_number
        - registration_type
        - country
        - address
      properties:
        type:
          type: string
          enum:
            - BUSINESS
          description: 'Discriminator: indicates this is business metadata'
        legal_entity:
          type: string
          description: Legal name of the business entity
          example: Nigerian Imports Ltd.
        registration_number:
          type: string
          description: Business registration number
          example: RC-123456-NGR
        registration_type:
          $ref: '#/components/schemas/RegistrationType'
        country:
          type: string
          description: Country where the business is registered
          example: NG
        city:
          type: string
          description: City where the business is located
          example: Lagos Island
        postal_code:
          type: string
          description: Postal code of the business address
          example: '10010'
        address:
          type: string
          description: Primary address of the business
          example: 15 Marina Street
        address_line_2:
          type: string
          description: Secondary address line
          example: Suite 200
    RegistrationType:
      type: string
      description: Business registration/identification type
      enum:
        - AIIN
        - BANK
        - BOID
        - CBID
        - CHID
        - CINC
        - COID
        - CUST
        - DUNS
        - EMPL
        - GS1G
        - SREN
        - SRET
        - TXID
        - USCC
      x-enum-descriptions:
        AIIN: Issuer Identification Number
        BANK: Bank Party Identification
        BOID: BusinessOtherIdentification
        CBID: Central Bank Identification Number
        CHID: Clearing Identification Number
        CINC: Certificate Of Incorporation Number
        COID: Country Identification Code
        CUST: Customer Number
        DUNS: Data Universal Numbering System
        EMPL: Employer Identification Number
        GS1G: GS1GLN Identifier
        SREN: SIREN
        SRET: SIRET
        TXID: Tax Identification Number
        USCC: Unified Social Credit Code
      example: AIIN
    IndividualMetadata:
      type: object
      description: Metadata specific to individual partners
      required:
        - type
        - first_name
        - last_name
        - date_of_birth
        - country
        - address
        - identification_number
        - identification_type
      properties:
        type:
          type: string
          enum:
            - INDIVIDUAL
          description: 'Discriminator: indicates this is individual metadata'
        first_name:
          type: string
          description: First name of the individual
          example: John
        last_name:
          type: string
          description: Last name of the individual
          example: Doe
        date_of_birth:
          type: string
          format: date
          description: Date of birth of the individual
          example: '1990-05-15'
        identification_number:
          type: string
          description: Identification number of the individual
        identification_type:
          $ref: '#/components/schemas/IdentificationType'
        country:
          type: string
          description: Country of residence
          example: United States
        city:
          type: string
          description: City of residence
          example: New York
        postal_code:
          type: string
          description: Postal code of residence
          example: '10001'
        address:
          type: string
          description: Primary address of residence
          example: 123 Main Street
        address_line_2:
          type: string
          description: Secondary address line
          example: Suite 200
    IdentificationType:
      type: string
      description: Identification type for the individual identifier
      enum:
        - AIIN
        - ARNU
        - CCPT
        - DRLC
        - NIDN
        - POID
        - SOS
        - TXID
      x-enum-descriptions:
        AIIN: Issuer Identification Number
        ARNU: Alien Registration Number
        CCPT: Passport Number
        DRLC: Driver's License Number
        NIDN: National Identity Number
        POID: PersonCommercialIdentification
        SOS: Social Security Number
        TXID: Tax Identification Number
      example: CCPT
    PartnerStatus:
      type: string
      description: Partner status for collection links or channels
      enum:
        - PENDING
        - ON_HOLD
        - FAILED
        - ACTIVATED
        - DEACTIVATED
      x-enum-descriptions:
        PENDING: Partner is pending review
        ON_HOLD: Partner is on hold due to review
        FAILED: Partner has failed review
        ACTIVATED: Partner hs been activated
        DEACTIVATED: Partner has been deactivated
      example: PENDING
    AccountType:
      type: string
      description: Type of account
      enum:
        - CRYPTO
        - FIAT
      x-enum-descriptions:
        CRYPTO: Cryptocurrency account with blockchain wallet addresses
        FIAT: Fiat currency account with bank deposit instructions
      example: CRYPTO
    AccountStatus:
      type: string
      description: Status of the account
      enum:
        - PENDING
        - ACTIVE
        - INACTIVE
        - CLOSED
      x-enum-descriptions:
        PENDING: Account is pending activation
        ACTIVE: Account is active and ready to receive funds
        INACTIVE: Account is temporarily inactive
        CLOSED: Account has been closed
      example: ACTIVE
    RailType:
      type: string
      description: Type of payment rail
      enum:
        - BLOCKCHAIN
        - FEDWIRE
        - ACH
        - RTP
        - PIX
      x-enum-descriptions:
        BLOCKCHAIN: Blockchain network for cryptocurrency payments
        FEDWIRE: Federal Reserve Wire Network (USD)
        ACH: Automated Clearing House (USD)
        RTP: Real-Time Payments (USD)
        PIX: Brazilian instant payment system (BRL)
      example: BLOCKCHAIN
    Rail:
      type: object
      description: Payment rail with deposit instructions
      discriminator:
        propertyName: type
        mapping:
          BLOCKCHAIN: '#/components/schemas/BlockchainRail'
          FEDWIRE: '#/components/schemas/FedwireRail'
          ACH: '#/components/schemas/AchRail'
          RTP: '#/components/schemas/RtpRail'
          PIX: '#/components/schemas/PixRail'
      oneOf:
        - $ref: '#/components/schemas/BlockchainRail'
        - $ref: '#/components/schemas/FedwireRail'
        - $ref: '#/components/schemas/AchRail'
        - $ref: '#/components/schemas/RtpRail'
        - $ref: '#/components/schemas/PixRail'
    BlockchainRail:
      type: object
      description: Blockchain payment rail with network details
      required:
        - type
        - network
        - address
        - currency
      properties:
        type:
          type: string
          enum:
            - BLOCKCHAIN
          description: 'Discriminator: indicates blockchain rail'
        network:
          $ref: '#/components/schemas/Network'
        address:
          type: string
          description: Blockchain wallet address for receiving funds
          example: '0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5'
        currency:
          type: string
          description: Cryptocurrency asset symbol
          example: USDC
    FedwireRail:
      type: object
      description: Fedwire payment rail for USD wire transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - FEDWIRE
          description: 'Discriminator: indicates Fedwire rail'
        account_number:
          type: string
          description: Bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        memo:
          type: string
          description: Reference memo to include with the transfer
          example: ACC-123456
    AchRail:
      type: object
      description: ACH payment rail for USD domestic transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - ACH
          description: 'Discriminator: indicates ACH rail'
        account_number:
          type: string
          description: Bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code (optional for ACH)
          example: CHASUS33
        memo:
          type: string
          description: Reference memo to include with the transfer
          example: ACC-123456
    RtpRail:
      type: object
      description: RTP (Real-Time Payments) rail for instant USD transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - RTP
          description: 'Discriminator: indicates RTP rail'
        account_number:
          type: string
          description: Bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code (optional for RTP)
          example: CHASUS33
        memo:
          type: string
          description: Reference memo to include with the transfer
          example: ACC-123456
    PixRail:
      type: object
      description: PIX payment rail for instant BRL transfers in Brazil
      required:
        - type
        - pix_key
        - pix_key_type
      properties:
        type:
          type: string
          enum:
            - PIX
          description: 'Discriminator: indicates PIX rail'
        pix_key:
          type: string
          description: PIX key for receiving payments
          example: '12345678901'
        pix_key_type:
          type: string
          description: Type of PIX key
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - RANDOM
          example: CPF
        beneficiary_name:
          type: string
          description: Name of the beneficiary as registered with PIX
          example: Empresa ABC Ltda
    SourcePaymentMethod:
      type: object
      description: Source payment method details for a transaction
      discriminator:
        propertyName: type
        mapping:
          BLOCKCHAIN: '#/components/schemas/BlockchainSourcePaymentMethod'
          FEDWIRE: '#/components/schemas/FedwireSourcePaymentMethod'
          ACH: '#/components/schemas/AchSourcePaymentMethod'
          RTP: '#/components/schemas/RtpSourcePaymentMethod'
          PIX: '#/components/schemas/PixSourcePaymentMethod'
      oneOf:
        - $ref: '#/components/schemas/BlockchainSourcePaymentMethod'
        - $ref: '#/components/schemas/FedwireSourcePaymentMethod'
        - $ref: '#/components/schemas/AchSourcePaymentMethod'
        - $ref: '#/components/schemas/RtpSourcePaymentMethod'
        - $ref: '#/components/schemas/PixSourcePaymentMethod'
    BlockchainSourcePaymentMethod:
      type: object
      description: >-
        Blockchain/crypto source payment method with on-chain transaction
        details
      required:
        - type
        - network
        - transaction_hash
        - block_id
        - source_address
        - destination_address
        - gas_fee
      properties:
        type:
          type: string
          enum:
            - BLOCKCHAIN
          description: 'Discriminator: indicates blockchain payment method'
        network:
          $ref: '#/components/schemas/Network'
        transaction_hash:
          type: string
          description: Blockchain transaction hash
          example: 0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u
        block_id:
          type: string
          description: Blockchain block identifier containing this transaction
          example: 0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85
        source_address:
          type: string
          description: Blockchain address from which funds were sent
          example: '0x880f622a1933ACf82bFC5e630c9ab7f18eF47809'
        destination_address:
          type: string
          description: Blockchain address to which funds were sent
          example: '0x02937b288b588058533C48b18EdFDdd76A324D6'
        gas_fee:
          type: object
          description: Blockchain gas fee details
          properties:
            value:
              type: string
              description: Gas fee value
              example: '0.0045'
            asset:
              type: string
              description: Asset used to pay gas fee
              example: ETH
    FedwireSourcePaymentMethod:
      type: object
      description: Fedwire source payment method for USD wire transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - FEDWIRE
          description: 'Discriminator: indicates Fedwire payment method'
        account_number:
          type: string
          description: Source bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        memo:
          type: string
          description: Reference memo included with the transfer
          example: Payment for invoice INV-2024-001
    AchSourcePaymentMethod:
      type: object
      description: ACH source payment method for USD domestic transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - ACH
          description: 'Discriminator: indicates ACH payment method'
        account_number:
          type: string
          description: Source bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code (optional for ACH)
          example: CHASUS33
        memo:
          type: string
          description: Reference memo included with the transfer
          example: Payment for invoice INV-2024-001
    RtpSourcePaymentMethod:
      type: object
      description: RTP (Real-Time Payments) source payment method for instant USD transfers
      required:
        - type
        - account_number
        - routing_number
      properties:
        type:
          type: string
          enum:
            - RTP
          description: 'Discriminator: indicates RTP payment method'
        account_number:
          type: string
          description: Source bank account number
          example: '1234567890'
        routing_number:
          type: string
          description: ABA routing number
          example: '021000021'
        swift_code:
          type: string
          description: SWIFT/BIC code (optional for RTP)
          example: CHASUS33
        memo:
          type: string
          description: Reference memo included with the transfer
          example: Payment for invoice INV-2024-001
    PixSourcePaymentMethod:
      type: object
      description: PIX source payment method for instant BRL transfers in Brazil
      required:
        - type
        - pix_key
        - pix_key_type
      properties:
        type:
          type: string
          enum:
            - PIX
          description: 'Discriminator: indicates PIX payment method'
        pix_key:
          type: string
          description: PIX key used for the payment
          example: '12345678901'
        pix_key_type:
          type: string
          description: Type of PIX key
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - RANDOM
          example: CPF
        sender_name:
          type: string
          description: Name of the sender as registered with PIX
          example: João Silva
    CreateAccountRequest:
      type: object
      description: Request payload for creating a new account
      required:
        - beneficiary_id
        - currency
      properties:
        beneficiary_id:
          type: string
          format: uuid
          description: >-
            Unique identifier of the beneficiary partner who will own this
            account
          example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
        currency:
          type: string
          description: >-
            Currency for the account (crypto: RLUSD, USDC, USDT or fiat: USD,
            BRL)
          example: USD
    Account:
      type: object
      description: Account for receiving payments with associated rails
      required:
        - id
        - account_owner_id
        - currency
        - type
        - rails
        - balances
        - ownership_level
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the account
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_owner_id:
          type: string
          format: uuid
          description: Unique identifier of the account owner can be customer or partner
          example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
        currency:
          type: string
          description: Currency for the account
          example: USD
        type:
          $ref: '#/components/schemas/AccountType'
        rails:
          type: array
          description: Available payment rail types for this account
          items:
            $ref: '#/components/schemas/RailType'
        balances:
          type: object
          description: Account balance information
          required:
            - available
            - pending
          properties:
            available:
              type: object
              description: Available balance that can be withdrawn or used
              required:
                - amount
              properties:
                amount:
                  type: string
                  description: Available balance amount as a string to preserve precision
                  example: '1250.50'
            pending:
              type: object
              description: Pending balance information
              required:
                - inbound
                - outbound
              properties:
                inbound:
                  type: object
                  description: Pending inbound balance
                  required:
                    - amount
                  properties:
                    amount:
                      type: string
                      description: Pending inbound amount as a string to preserve precision
                      example: '50.00'
                outbound:
                  type: object
                  description: Pending outbound balance
                  required:
                    - amount
                  properties:
                    amount:
                      type: string
                      description: >-
                        Pending outbound amount as a string to preserve
                        precision
                      example: '25.00'
        ownership_level:
          type: string
          description: >-
            Indicates whether this account is owned at the partner or customer
            level
          enum:
            - PARTNER
            - CUSTOMER
          x-enum-descriptions:
            PARTNER: >-
              Account owned by a specific partner (beneficiary). Funds in this
              account are moved to a customer-level accounts for the same
              currency.
            CUSTOMER: >-
              Account owned at the customer level. Eligible for settlement and
              receiving funds from partner accounts.
          example: PARTNER
        status:
          $ref: '#/components/schemas/AccountStatus'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was created
          example: '2025-09-18T22:54:00.542Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was last updated
          example: '2025-09-18T22:54:00.542Z'
    CollectionStatus:
      type: string
      description: The status of the collection
      enum:
        - CREATED
        - CLOSED
        - HOLD
        - EXPIRED
        - PENDING
        - PROCESSING
        - COMPLETED
        - UNDERPAID
        - OVERPAID
        - CANCELLED
      x-enum-descriptions:
        CREATED: Collection has been created
        CLOSED: Collection has been closed
        HOLD: Collection is on hold
        EXPIRED: Collection has expired
        PENDING: Collection is pending
        PROCESSING: Collection is being processed
        COMPLETED: Collection has been completed
        UNDERPAID: Collection has been underpaid
        OVERPAID: Collection has been overpaid
        CANCELLED: Collection has been cancelled
      example: PENDING
    FeeMode:
      type: string
      description: How fees are handled in the collection
      enum:
        - INCLUDED
        - EXCLUDED
      x-enum-descriptions:
        INCLUDED: >-
          Fee is included in the collection net amount based on the receiving
          currency specified by the user
        EXCLUDED: >-
          Fee is excluded from the collection net amount based on the receiving
          currency specified by the user
      example: EXCLUDED
    TransactionV1:
      type: object
      description: Transaction details
      required:
        - id
        - parent_id
        - account_id
        - payer
        - beneficiary
        - payment_amount
        - account_equivalent
        - market_rate
        - exchange_rate
        - source_payment_method
        - status
        - transaction_processed_date
        - date_created
        - date_confirmed
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the transaction
          example: 487ba009-56cf-4ad9-8b5c-045e27893e00
        parent_id:
          type: string
          format: uuid
          description: >-
            Identifier of the parent entity (collection link or channel) for
            this transaction
          example: e8d43598-107d-4694-9fb2-934e7484c3d4
        account_id:
          type: string
          format: uuid
          description: Identifier of the account associated with this transaction
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        settlement_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Identifier of the settlement associated with this transaction. Null
            if the transaction has not been included in a settlement yet.
          example: 9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e
        payer:
          type: object
          description: Payer partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the payer partner
              example: 0c5479ff-3772-4123-b2b7-e679e71eb570
            name:
              type: string
              description: Full name of the payer partner
              example: Nigerian Imports Ltd.
            email:
              type: string
              description: Email address of the payer partner
              format: email
              example: nigerian@imports.com
        beneficiary:
          type: object
          description: Beneficiary partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier of the beneficiary partner
              example: 01467076-8bb0-41c1-ad54-5751dd4a9e80
            name:
              type: string
              description: Full name of the beneficiary partner
              example: Hong Kong Exports Ltd.
            email:
              type: string
              description: Email address of the beneficiary partner
              format: email
              example: hongkong@exports.com
        payment_amount:
          type: object
          description: Payment amount and asset
          required:
            - value
            - asset
          properties:
            value:
              type: string
              description: Payment amount as a string to preserve precision
              example: '50.00000000'
            asset:
              type: string
              description: Asset symbol of the payment
              example: USDT
        account_equivalent:
          type: object
          description: >-
            Account equivalent amounts for payment, fee, and net (converted to
            account's native currency)
          required:
            - gross_amount
            - fee_amount
            - net_amount
          properties:
            gross_amount:
              type: object
              required:
                - value
                - currency
              properties:
                value:
                  type: string
                  description: Gross amount in account currency
                  example: '50.00'
                currency:
                  type: string
                  description: Account currency code
                  example: USD
            fee_amount:
              type: object
              required:
                - value
                - currency
              properties:
                value:
                  type: string
                  description: Fee amount in account currency
                  example: '0.50'
                currency:
                  type: string
                  description: Account currency code
                  example: USD
            net_amount:
              type: object
              required:
                - value
                - currency
              properties:
                value:
                  type: string
                  description: Net amount in account currency
                  example: '49.50'
                currency:
                  type: string
                  description: Account currency code
                  example: USD
        market_rate:
          type: object
          description: Market rate reference for the transaction
          properties:
            base:
              type: string
              description: Base currency for the exchange rate
              example: USDT
            counter:
              type: string
              description: Counter currency for the exchange rate
              example: USD
            rate:
              type: string
              description: Exchange rate from base to counter currency
              example: '1.00'
        exchange_rate:
          type: object
          description: Exchange rate applied on the transaction
          properties:
            base:
              type: string
              description: Base currency for the exchange rate
              example: USDT
            counter:
              type: string
              description: Counter currency for the exchange rate
              example: USD
            rate:
              type: string
              description: Exchange rate from base to counter currency
              example: '0.99'
        source_payment_method:
          $ref: '#/components/schemas/SourcePaymentMethod'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        reason:
          type: string
          nullable: true
          description: Reason for current status (if applicable)
          example: null
        transaction_processed_date:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the transaction
          example: '2025-06-17T12:20:00Z'
        date_created:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when transaction was created
          example: 1566203005000
        date_confirmed:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) when transaction was confirmed
          example: 1566203005000
    TransactionStatus:
      type: string
      description: Transaction status
      enum:
        - COMPLETED
        - FAILED_KYT
        - FAILED
        - HOLD_KYT
        - REFUNDED_KYT
        - PROCESSING
      x-enum-descriptions:
        COMPLETED: Funds have been successfully converted into the desired currency
        HOLD_KYT: Funds have been held for our KYT checks
        FAILED_KYT: Funds have failed our KYT checks
        REFUNDED_KYT: Funds have been refunded based on our kyt checks
        PROCESSING: Funds are settled and being processed in our system
        FAILED: Funds have failed transaction processing and will not be settled
      example: COMPLETED
    SettlementType:
      type: string
      description: Settlement type
      enum:
        - FIAT
        - CRYPTO
      x-enum-descriptions:
        FIAT: Settlement of fiat currency
        CRYPTO: Settlement of crypto currency
      example: FIAT
    SettlementStatus:
      type: string
      description: Settlement status
      enum:
        - PENDING
        - PROCESSING
        - COMPLETED
        - FAILED
        - CANCELLED
      x-enum-descriptions:
        PENDING: Settlement is pending
        PROCESSING: Settlement is being processed
        COMPLETED: Settlement has been completed
        FAILED: Settlement has failed
        CANCELLED: Settlement has been cancelled
      example: PENDING
    SettlementAccountDetails:
      type: object
      description: Account details for settlement transactions
      required:
        - account_holder
        - institution_name
        - account_number
        - routing_number
      properties:
        account_holder:
          type: string
          description: Full name of the account holder
          example: John Doe
        institution_name:
          type: string
          description: Name of the financial institution
          example: Bank of America
        account_number:
          type: string
          description: Account number for the settlement
          example: XXXX6789
        routing_number:
          type: string
          description: Routing number for the financial institution
          example: XXXX4321
    FiatSettlementDataV1:
      type: object
      description: Settlement data for fiat settlements
      required:
        - type
        - sending_account
        - receiving_account
      properties:
        type:
          type: string
          enum:
            - FIAT
          description: Discriminator for fiat settlement data
          example: FIAT
        sending_account:
          $ref: '#/components/schemas/SettlementAccountDetails'
        receiving_account:
          $ref: '#/components/schemas/SettlementAccountDetails'
        transaction_reference_numbers:
          type: array
          items:
            type: string
          description: Bank reference numbers for the settlement transaction
          example:
            - ABC12345
        description:
          type: string
          description: Human-readable description of the settlement
          example: Monthly Payout
    CryptoSettlementDataV1:
      type: object
      description: Settlement data for crypto settlements
      required:
        - type
        - network
        - transaction_hash
        - block_id
        - source_address
        - destination_address
        - gas_fee
      properties:
        type:
          type: string
          enum:
            - CRYPTO
          description: Discriminator for crypto settlement data
          example: CRYPTO
        network:
          $ref: '#/components/schemas/Network'
        transaction_hash:
          type: string
          description: Blockchain transaction hash
          example: 0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u
        block_id:
          type: string
          description: Blockchain block identifier containing this transaction
          example: 0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85
        source_address:
          type: string
          description: Blockchain address from which funds were sent
          example: '0x880f622a1933ACf82bFC5e630c9ab7f18eF47809'
        destination_address:
          type: string
          description: Blockchain address to which funds were sent
          example: '0x02937b288b588058533C48b18EdFDdd76A324D6'
        gas_fee:
          type: object
          description: Blockchain gas fee details
          required:
            - value
            - asset
          properties:
            value:
              type: string
              description: Gas fee value
              example: '0.0045'
            asset:
              type: string
              description: Asset used to pay gas fee
              example: ETH
    SettlementDataV1:
      description: Settlement data - varies based on settlement type (FIAT or CRYPTO)
      oneOf:
        - $ref: '#/components/schemas/FiatSettlementDataV1'
        - $ref: '#/components/schemas/CryptoSettlementDataV1'
      discriminator:
        propertyName: type
        mapping:
          FIAT: '#/components/schemas/FiatSettlementDataV1'
          CRYPTO: '#/components/schemas/CryptoSettlementDataV1'
    SettlementTransactionV1:
      type: object
      description: Settlement transaction details
      required:
        - id
        - account_id
        - amount
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the settlement transaction
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_id:
          type: string
          format: uuid
          description: Account ID associated with this settlement transaction
          example: f9e8d7c6-b5a4-3210-fedc-ba0987654321
        market_rate:
          type: object
          description: Market rate at the time of settlement
          properties:
            base:
              type: string
              description: Base currency for the exchange rate
              example: USDC
            counter:
              type: string
              description: Counter currency for the exchange rate
              example: USD
            rate:
              type: string
              description: Exchange rate from base to counter currency
              example: '1.00'
        exchange_rate:
          type: object
          description: Exchange rate from base to counter currency
          properties:
            base:
              type: string
              description: Base currency for the exchange rate
              example: USDC
            counter:
              type: string
              description: Counter currency for the exchange rate
              example: USD
            rate:
              type: string
              description: Exchange rate from base to counter currency
              example: '0.99'
        amount:
          type: string
          pattern: ^[0-9]+(\.[0-9]{1,8})?$
          example: '49.50'
    CreateSettlementRequestV1:
      type: object
      description: Request to create a new settlement
      required:
        - source_account_id
        - amount
        - currency
      properties:
        source_account_id:
          type: string
          format: uuid
          description: Source customer account ID for the settlement
          example: b2c3d4e5-f6a7-8901-bcde-f12345678901
        amount:
          type: string
          description: Amount for the settlement
          example: '100.00'
        currency:
          type: string
          description: Currency for the settlement
          example: USD
        network:
          type: string
          description: Network for crypto settlements (only applicable when type is CRYPTO)
    SettlementV1:
      type: object
      description: Complete settlement information
      required:
        - id
        - type
        - currency
        - gross_amount
        - settlement_amount
        - fees
        - status
        - data
        - settlement_transactions
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the settlement
          example: 63dd59dd-88be-41a2-a246-2f6724209422
        type:
          $ref: '#/components/schemas/SettlementType'
        currency:
          type: string
          description: Currency code for the settlement
          example: USD
        gross_amount:
          type: string
          description: Total settlement amount before fees
          example: '50.00'
        settlement_amount:
          type: string
          description: Net settlement amount after fees
          example: '49.50'
        fees:
          type: object
          description: Settlement fees
          properties:
            transaction_fees:
              type: string
              description: Total fees applied to the settlement
              example: '0.50'
        status:
          $ref: '#/components/schemas/SettlementStatus'
        data:
          $ref: '#/components/schemas/SettlementDataV1'
        settlement_transactions:
          type: array
          description: List of settlement transactions
          items:
            $ref: '#/components/schemas/SettlementTransactionV1'
    ChannelStatus:
      type: string
      description: Status of the channel
      enum:
        - ACTIVE
        - INACTIVE
        - CLOSED
      x-enum-descriptions:
        ACTIVE: Channel is active
        INACTIVE: Channel is inactive
        CLOSED: Channel is closed
      example: ACTIVE
    CreateChannelRequestV1:
      type: object
      description: Request payload for creating a new channel using account-based routing
      required:
        - payer_id
        - account_id
      properties:
        payer_id:
          type: string
          format: uuid
          description: Unique identifier of the payer partner
          example: e471b938-98ad-45e4-b144-53a556ea047d
        account_id:
          type: string
          format: uuid
          description: Unique identifier of the account to receive funds
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        payment_currencies:
          type: array
          description: >-
            List of currencies accepted for payment on this channel. If not
            specified, defaults to the account's supported currencies.
          items:
            type: string
            enum:
              - USD
              - BRL
              - USDT
              - USDC
              - RLUSD
          example:
            - USD
            - USDC
    ChannelV1:
      type: object
      description: Channel information with account-based routing
      required:
        - id
        - payer
        - beneficiary
        - account
        - payment_methods
        - payment_link
        - transactions
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the channel
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        payer:
          type: object
          description: Payer partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the payer partner
              example: e471b938-98ad-45e4-b144-53a556ea047d
            name:
              type: string
              description: Full name of the payer partner
              example: Nigerian Imports Ltd.
            email:
              type: string
              format: email
              description: Email address of the payer partner
              example: nigerian@imports.com
        beneficiary:
          type: object
          description: Beneficiary partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier of the beneficiary partner
              example: 01467076-8bb0-41c1-ad54-5751dd4a9e80
            name:
              type: string
              description: Full name of the beneficiary partner
              example: Hong Kong Exports Ltd.
            email:
              type: string
              description: Email address of the beneficiary partner
              format: email
              example: hongkong@exports.com
        account:
          type: object
          description: Account associated to this channel, which funds will be routed to
          required:
            - id
            - beneficiary_id
            - currency
            - type
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the account
              example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            beneficiary_id:
              type: string
              format: uuid
              description: Unique identifier of the beneficiary partner
              example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
            currency:
              type: string
              description: Currency for the account
              example: USD
            type:
              type: string
              description: Type of account
              enum:
                - FIAT
                - CRYPTO
              example: FIAT
        payment_methods:
          type: array
          description: Available payment methods with full deposit instructions
          items:
            $ref: '#/components/schemas/Rail'
        payment_link:
          type: string
          format: uri
          description: URL for payer UI to access this channel
          example: >-
            https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6
        transactions:
          type: array
          description: List of transactions associated with this channel
          items:
            $ref: '#/components/schemas/TransactionV1'
        status:
          $ref: '#/components/schemas/ChannelStatus'
        reason:
          type: string
          nullable: true
          description: Reason for current status (if applicable)
          example: null
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the channel was created
          example: '2025-09-18T22:54:00.542Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the channel was last updated
          example: '2025-09-18T22:54:00.542Z'
    CreateCollectionRequestV1:
      type: object
      description: >-
        Request payload for creating a new collection using account-based
        routing
      required:
        - payer_id
        - account_id
        - amount
        - link_expiry
        - return_url
      properties:
        payer_id:
          type: string
          format: uuid
          description: Unique identifier of the payer partner
          example: 0c5479ff-3772-4123-b2b7-e679e71eb570
        account_id:
          type: string
          format: uuid
          description: Unique identifier of the account to receive funds
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        amount:
          type: string
          description: Collection amount as a string to preserve precision
          pattern: ^[0-9]+(\.[0-9]{1,8})?$
          example: '800.00'
        fee_mode:
          allOf:
            - $ref: '#/components/schemas/FeeMode'
          default: EXCLUDED
        reference_id:
          type: string
          description: External reference identifier for the collection
          example: INV-2025-009
        description:
          type: string
          description: Human-readable description of the collection purpose
          example: 'Payment for Order #2668'
        link_expiry:
          type: integer
          description: Payment link expiry time in seconds from creation
          minimum: 300
          maximum: 2592000
          example: 172800
        return_url:
          type: string
          format: uri
          description: URL to redirect user after payment completion
          example: https://example.com/payment/completion
    CollectionV1:
      type: object
      description: Collection information with account-based routing
      required:
        - id
        - payer
        - beneficiary
        - account
        - gross_amount
        - net_amount
        - fee_mode
        - fee
        - amount_remaining
        - description
        - link_expiry
        - return_url
        - expires_at
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the collection
          example: e8d43598-107d-4694-9fb2-934e7484c3d4
        payer:
          type: object
          description: Payer partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the payer partner
              example: 0c5479ff-3772-4123-b2b7-e679e71eb570
            name:
              type: string
              description: Full name of the payer partner
              example: Nigerian Imports Ltd.
            email:
              type: string
              description: Email address of the payer partner
              format: email
              example: nigerian@imports.com
        beneficiary:
          type: object
          description: Beneficiary partner details
          required:
            - id
            - name
            - email
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier of the beneficiary partner
              example: 01467076-8bb0-41c1-ad54-5751dd4a9e80
            name:
              type: string
              description: Full name of the beneficiary partner
              example: Hong Kong Exports Ltd.
            email:
              type: string
              description: Email address of the beneficiary partner
              format: email
              example: hongkong@exports.com
        account:
          type: object
          description: Account associated to this collection, which funds will be routed to
          required:
            - id
            - beneficiary_id
            - currency
            - type
          properties:
            id:
              type: string
              format: uuid
              description: Unique identifier for the account
              example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            beneficiary_id:
              type: string
              format: uuid
              description: Unique identifier of the beneficiary partner
              example: 291ecf34-a01d-466a-b0fd-662a88b7a1bb
            currency:
              type: string
              description: Currency for the account
              example: USD
            type:
              type: string
              description: Type of account
              enum:
                - FIAT
                - CRYPTO
              example: FIAT
        reference_id:
          type: string
          description: External reference identifier for the collection
          example: INV-2025-009
        gross_amount:
          type: string
          description: Total amount including fees
          example: '808.00'
        net_amount:
          type: string
          description: Amount excluding buyer fees
          example: '800.00'
        fee_mode:
          $ref: '#/components/schemas/FeeMode'
        fee:
          type: string
          description: Fee amount charged for the collection
          example: '8.00'
        amount_remaining:
          type: string
          description: Amount remaining for an incomplete payment
          example: '758.50'
        description:
          type: string
          description: Human-readable description of the collection purpose
          example: 'Payment for Order #2668'
        link_expiry:
          type: integer
          description: Payment link expiry time in seconds from creation
          example: 172800
        return_url:
          type: string
          format: uri
          example: https://example.com/payment/completion
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the collection expires
          example: '2025-06-30T23:59:59Z'
        transactions:
          type: array
          description: List of transactions associated with this collection
          items:
            $ref: '#/components/schemas/TransactionV1'
        payment_link:
          type: string
          format: uri
          description: URL for the payment interface
          example: https://collections.ripple.com/link/pay/384c5f9b
        status:
          $ref: '#/components/schemas/CollectionStatus'
        reason:
          type: string
          nullable: true
          description: Reason for current status (if applicable)
          example: null
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the collection was created
          example: '2025-06-17T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the collection was last updated
          example: '2025-06-17T12:30:00Z'
    Network:
      type: string
      description: Supported blockchain networks
      enum:
        - ETHEREUM
        - ETHEREUM_SEPOLIA_TESTNET
        - SOLANA
        - SOLANA_TESTNET
        - XRPL
        - XRPL_TESTNET
      example: ETHEREUM
    EventType:
      type: string
      description: Event type for which a webhook can be created.
      enum:
        - WEBHOOK_CREATED
        - WEBHOOK_UPDATED
        - WEBHOOK_DELETED
        - TRANSACTION_STATUS_CHANGED
        - PARTNER_STATUS_CHANGED
        - WALLET_ADDRESS_CREATED
        - WALLET_ADDRESS_ROTATED
        - SETTLEMENT_INITIATED
        - SETTLEMENT_COMPLETED
        - SETTLEMENT_FAILED
        - CHANNEL_CREATED
        - CHANNEL_ARCHIVED
        - ACCOUNT_CREATED
        - ACCOUNT_STATUS_CHANGED
        - ACCOUNT_BALANCE_UPDATED
      x-enum-descriptions:
        WEBHOOK_CREATED: Fired when a new webhook subscription is created
        WEBHOOK_UPDATED: Fired when a webhook subscription is updated
        WEBHOOK_DELETED: Fired when a webhook subscription is deleted
        TRANSACTION_STATUS_CHANGED: Fired when a transaction status changes
        PARTNER_STATUS_CHANGED: Fired when a partner status changes
        WALLET_ADDRESS_CREATED: Fired when a new wallet address is created
        WALLET_ADDRESS_ROTATED: Fired when a wallet address is rotated
        SETTLEMENT_INITIATED: Fired when a settlement is initiated
        SETTLEMENT_COMPLETED: Fired when a settlement is completed
        SETTLEMENT_FAILED: Fired when a settlement fails
        CHANNEL_CREATED: Fired when a new channel is created
        CHANNEL_ARCHIVED: Fired when a channel is archived
        ACCOUNT_CREATED: Fired when a new account is created for a beneficiary
        ACCOUNT_STATUS_CHANGED: Fired when an account status changes (e.g., ACTIVE, SUSPENDED, CLOSED)
        ACCOUNT_BALANCE_UPDATED: Fired when an account balance is updated after transactions settle
      example: TRANSACTION_STATUS_CHANGED
    CreateWebhookRequest:
      type: object
      required:
        - callback_url
        - event_types
      properties:
        callback_url:
          type: string
          format: uri
          description: HTTPS URL to POST events to.
          example: https://webhook.partner.example/webhooks
        event_types:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EventType'
    UpdateWebhookRequest:
      type: object
      required:
        - callback_url
      properties:
        callback_url:
          type: string
          format: uri
          description: HTTPS URL to POST events to.
          example: https://webhook-updated.partner.example/webhooks
    WebhookResponse:
      type: object
      required:
        - id
        - event_type
        - callback_url
        - signature_verification_key
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the webhook.
          example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
        event_type:
          allOf:
            - $ref: '#/components/schemas/EventType'
          example: TRANSACTION_STATUS_CHANGED
        callback_url:
          type: string
          format: uri
          description: HTTPS URL to which events will be sent.
          example: https://webhook.partner.example/webhooks
        signature_verification_key:
          type: string
          description: Hex-encoded public key used to verify webhook signatures.
          example: >-
            04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8
    AuthErrorResponse:
      description: >-
        The response object containing the error and its description if the
        authentication call fails.
      properties:
        error_description:
          type: string
          description: Summary of the returned problem.
          example: Unauthorized
        error:
          type: string
          description: Error status.
          example: access_denied
    Error:
      type: object
      description: Standard error response format
      required:
        - code
        - reason
      properties:
        code:
          type: string
          description: Error code identifying the type of error
        reason:
          type: string
          description: Human-readable error message
    PageMetadata:
      type: object
      description: Pagination metadata.
      properties:
        page:
          type: integer
          example: 1
        size:
          type: integer
          example: 10
        total_elements:
          type: integer
          example: 100
        total_pages:
          type: integer
          example: 10
      required:
        - page
        - size
        - total_elements
        - total_pages
