openapi: 3.1.0
info:
  title: Almond Settlement API
  description: >
    The Almond Settlement API enables clients to move funds cross-border by
    leveraging blockchain as the transfer layer.


    As a client, you need to:

      - Authenticate to obtain an access token.
      - Check Settlement Rates for transparency.
      - Create a Settlement with relevant details.

    Almond then fully automates the orchestration — buying crypto, transferring
    it across the blockchain, swapping it into destination currency, and
    depositing it into the recipient's  local bank account(or the account under
    the payout partner) — sending notifications upon successful completion.


    <p align="center">

    <img src="/images/settlement_flow_final.png" alt="System Flow"
    width="900"/><br>

    <span style="font-size:0.9em;">Figure: Settlement Flow</span>

    </p>
  version: 1.1.0
  contact:
    name: Almond Fintech API Support
    url: https://www.almondfintech.com/contact-us
    email: info@almondfintech.com
  license:
    name: Copyright © 2025 Almond FinTech. All rights reserved.
    url: https://almondfintech.com
servers:
  - url: https://api.sandbox.almondfintech.com
    description: Sandbox
  - url: https://api.almondfintech.com
    description: Production
paths:
  /v2/settlement-rates:
    get:
      tags:
        - Settlement Rate
      operationId: getSettlementRate
      summary: Get Settlement Rate
      description: >
        Retrieves the guaranteed/locked exchange rate for settlement along with
        forecast rates for different execution intervals.


        **Rate Information Includes:**

        - **Current Rate**: locked exchange rate for immediate execution

        - **Rate ID**: Unique identifier of the rate

        - **Forecast Rates**: Forecast rates for execution at different time
        intervals (1-6 hours)

        - **Corridor Information**: Source and destination member IDs


        **Rate Locking:**

        - Each rate response includes a `rateId` that locks the current rate

        - This `rateId` must be used when creating a settlement to guarantee the
        rate

        - Rate locks have an expiry time (typically 15 minutes for immediate
        execution)


        **Forecast Rates:**

        - Provides rates for scheduled execution

        - Available intervals: IMMEDIATE, ONE_HOUR, TWO_HOURS, THREE_HOURS,
        FOUR_HOURS, FIVE_HOURS, SIX_HOURS

        - Helps members choose optimal execution timing based on rate forecasts
      security:
        - OAuth2:
            - settlements
      parameters:
        - name: destinationCcy
          in: query
          required: true
          description: ISO 4217 three-letter currency code for the destination currency.
          schema:
            type: string
            pattern: ^[A-Z]{3}$
            example: PHP
      responses:
        '200':
          description: Rate information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementRateResponse'
              examples:
                settlementRate:
                  summary: settlement rate
                  description: settlement rate for 'PHP' destinationCcy
                  value:
                    rate: 55.75
                    rateId: c162d93e-dfac-4d26-8da3-b3b76f8ca3e0
                    sourceMemberId: SOURCE_MEMBER
                    destinationMemberId: DEST_MEMBER_1
                    forecastRates:
                      - executionInterval: IMMEDIATE
                        rate: 55.75
                      - executionInterval: ONE_HOUR
                        rate: 55.76115
                      - executionInterval: TWO_HOURS
                        rate: 55.7723
                      - executionInterval: THREE_HOURS
                        rate: 55.78345
                      - executionInterval: FOUR_HOURS
                        rate: 55.7946
                      - executionInterval: FIVE_HOURS
                        rate: 55.80575
                      - executionInterval: SIX_HOURS
                        rate: 55.8169
        '400':
          description: Rate not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/settlement-context:
    get:
      tags:
        - Settlement Context
      operationId: getSettlementContext
      summary: Get Settlement Context
      description: >
        Retrieves settlement context information, providing an overview of
        available settlement corridors and their current capacity.


        This endpoint can be used to understand the following before creating
        settlements.

        - Which destination members they can send settlements to

        - Maximum settlement amounts allowed for each corridor

        - Current settlement activity and capacity constraints:
      security:
        - OAuth2:
            - settlements
      parameters:
        - name: destinationMemberId
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z0-9_]*$
            example: DEST_MEMBER_1
          description: >
            Optional filter to get context for a specific destination member
            only.


            - If provided: Returns context for only that specific corridor

            - If omitted: Returns context for all available corridors
      responses:
        '200':
          description: Settlement context response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementContextInfo'
              examples:
                noDestinationMemberIdSpecified:
                  summary: Settlement context
                  description: Settlement context for all corridors
                  value:
                    sourceMemberId: SOURCE_MEMBER
                    currency: USD
                    corridors:
                      - destinationMemberId: DEST_MEMBER_1
                        inProgressSettlementsCount: 0
                        settlementInProgress: false
                        maxSettlementAmount: 50000
                      - destinationMemberId: DEST_MEMBER_2
                        inProgressSettlementsCount: 1
                        settlementInProgress: true
                        maxSettlementAmount: 50000
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/settlements:
    post:
      tags:
        - Settlement
      operationId: createSettlement
      summary: Create Settlement
      description: >
        Create a new settlement with the specified execution interval and locked
        rate.


        **Important Notes:**

        - Specified `destinationMemberId` must be a valid member ID that has an
        active corridor. Verify availability through `/v2/settlement-context`
        endpoint.

        - Rate ID must be obtained from `/v2/settlement-rates` endpoint first

        - Settlement amount cannot exceed the corridor's maximum limit available
        in `/v2/settlement-context` API


        **Execution Intervals:**

        - `IMMEDIATE`: Settlement executed as soon as possible (0 hours)

        - `ONE_HOUR` to `SIX_HOURS`: Settlement scheduled for future execution


        **Settlement States After Creation:**

        - `S100_SCHEDULED`: If execution interval is in the future

        - `S200_RECEIVED`: If immediate execution is requested
      security:
        - OAuth2:
            - settlements
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementRequest'
            examples:
              settlement:
                value:
                  destinationMemberId: DEST_MEMBER_1
                  settlementAmt: 1500
                  rateId: c162d93e-dfac-4d26-8da3-b3b76f8ca3e0
                  executionInterval: ONE_HOUR
                  notes: test settlement
      responses:
        '200':
          description: Settlement created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResponse'
              examples:
                successfulResponse:
                  value:
                    settlementId: a5740343-91db-4218-b5bd-8f4c8
                    settlementStatus: S100_RECEIVED
                    settlementAmt: 1500
                    pendingAmt: 1500
                    rate: 55.76115
                    settlementAmtReceived: 83641.725
                    sourceCcy: USD
                    destinationCcy: PHP
                    sourceMemberId: SOURCE_MEMBER
                    destinationMemberId: DEST_MEMBER_1
                    notes: test settlement
                    creationTime: '2024-01-15T10:30:00Z'
                    completionTime: null
                    dueDate: '2024-01-15T11:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
    get:
      tags:
        - Settlement
      operationId: getSettlements
      summary: Get Settlements
      description: >
        Retrieves a paginated list of settlements with optional filtering and
        sorting.


        **Available Filters:**

        - `destinationMemberId`: Filter by specific destination member

        - `settlementStatus`: Filter by settlement status (S100_SCHEDULED,
        S200_RECEIVED, etc.)

        - `createdAfter`: Filter settlements created after a specific date/time


        **Sorting Options:**

        - `sortField`: Field to sort by (creationTime, settlementAmt, rate,
        etc.)

        - `sortDirection`: ASC (ascending) or DESC (descending)


        **Pagination:**

        - `page`: Page number (0-based)

        - `size`: Number of records per page (default: 10)


        **Response includes:**

        - Array of settlement records

        - Pagination metadata (totalPages, totalRecords)

        - Settlement details for each record
      security:
        - OAuth2:
            - settlements
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/SortDirection'
        - name: sortField
          schema:
            $ref: '#/components/schemas/SettlementSortFieldEnum'
          in: query
          required: false
          description: Field to sort settlements
        - name: destinationMemberId
          in: query
          schema:
            type: string
            pattern: ^[A-Z0-9_]*$
            example: DEST_MEMBER_1
          description: Filter settlements for this specific destination member.
        - name: settlementStatus
          in: query
          schema:
            $ref: '#/components/schemas/SettlementStatusEnum'
          description: Filter settlements by current status
        - name: createdAfter
          in: query
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
          description: |
            Filter settlements created after this timestamp.
            Uses ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).
            Useful for retrieving only recent settlements.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementListResponse'
              examples:
                successfulResponse:
                  value:
                    settlements:
                      - settlementId: a5740343-91db-4218-b5bd-8f4c8
                        settlementStatus: S300_IN_PROGRESS
                        settlementAmt: 1500
                        pendingAmt: 750
                        rate: 55.76115
                        settlementAmtReceived: 83641.725
                        sourceCcy: USD
                        destinationCcy: PHP
                        sourceMemberId: SOURCE_MEMBER
                        destinationMemberId: DEST_MEMBER_1
                        notes: test settlement
                        creationTime: '2024-01-15T10:30:00Z'
                        completionTime: null
                        dueDate: '2024-01-15T11:30:00Z'
                    page: 0
                    size: 10
                    totalPages: 1
                    totalRecords: 1
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /v2/settlements/{settlement-id}:
    get:
      tags:
        - Settlement
      operationId: getSettlement
      summary: Get Settlement
      description: >
        Retrieves detailed information for a specific settlement by its unique
        identifier.


        **Response includes:**

        - Settlement details (amounts, rates, currencies, notes)

        - Current status and timestamps

        - Source and destination member information
      security:
        - OAuth2:
            - settlements
      parameters:
        - $ref: '#/components/parameters/SettlementId'
      responses:
        '200':
          description: Settlement Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResponse'
              examples:
                successfulResponse:
                  value:
                    settlements:
                      - settlementId: a5740343-91db-4218-b5bd-8f4c8
                        settlementStatus: S600_COMPLETED
                        settlementAmt: 1500
                        pendingAmt: 0
                        rate: 55.76115
                        settlementAmtReceived: 83641.725
                        sourceCcy: USD
                        destinationCcy: PHP
                        sourceMemberId: SOURCE_MEMBER
                        destinationMemberId: DEST_MEMBER_1
                        notes: test settlement
                        creationTime: '2024-01-15T10:30:00Z'
                        completionTime: '2024-01-15T11:32:00Z'
                        dueDate: '2024-01-15T11:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
components:
  schemas:
    ExecutionIntervalEnum:
      type: string
      description: >
        Settlement execution interval determining when the settlement will be
        processed.


        - `IMMEDIATE`: Execute settlement as soon as possible (0 hours delay)

        - `ONE_HOUR` to `SIX_HOURS`: Schedule settlement for future execution


        Execution intervals allow members to optimize settlement timing based
        on:

        - Market conditions and rate forecasts

        - Business requirements and cash flow needs

        - Operational schedules and working hours
      enum:
        - IMMEDIATE
        - ONE_HOUR
        - TWO_HOURS
        - THREE_HOURS
        - FOUR_HOURS
        - FIVE_HOURS
        - SIX_HOURS
      x-enum-values:
        - value: IMMEDIATE
          numeric: 0
        - value: ONE_HOUR
          numeric: 1
        - value: TWO_HOURS
          numeric: 2
        - value: THREE_HOURS
          numeric: 3
        - value: FOUR_HOURS
          numeric: 4
        - value: FIVE_HOURS
          numeric: 5
        - value: SIX_HOURS
          numeric: 6
    ForecastRate:
      type: object
      description: Forecast rate for a specific execution interval
      properties:
        executionInterval:
          $ref: '#/components/schemas/ExecutionIntervalEnum'
        rate:
          type: number
          description: rate for this execution interval.
    SettlementRateResponse:
      type: object
      properties:
        rate:
          type: number
          format: float
        rateId:
          type: string
        sourceMemberId:
          type: string
        destinationMemberId:
          type: string
        forecastRates:
          type: array
          items:
            $ref: '#/components/schemas/ForecastRate'
    ErrorInfo:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        detail:
          type: string
    CorridorSettlementContext:
      type: object
      description: >-
        Settlement corridor information showing capacity and current activity
        for a specific source-destination member pair.
      properties:
        destinationMemberId:
          type: string
          description: Destination member identifier.
        inProgressSettlementsCount:
          type: integer
          description: >
            Number of settlements currently in progress (not yet completed) for
            this corridor.


            Includes settlements in states:

            - S100_SCHEDULED (scheduled for future execution)

            - S200_RECEIVED (received and pending)

            - S300_IN_PROGRESS (actively processing)

            - S400_FIAT_WITHDRAWAL_IN_PROGRESS (final withdrawal stage)
        settlementInProgress:
          type: boolean
          description: >-
            Boolean flag indicating whether any settlements are currently in
            progress for this corridor. True if inProgressSettlementsCount > 0.
        maxSettlementAmount:
          type: number
          format: bigDecimal
          description: >-
            Maximum settlement amount allowed for this corridor in source
            currency.
    SettlementContextInfo:
      type: object
      properties:
        sourceMemberId:
          type: string
          description: Source member Identifier.
        currency:
          type: string
          description: >-
            Source currency supported by the source member for outbound
            settlements.
          pattern: ^[A-Z]{3}$
        corridors:
          type: array
          description: >-
            List of available corridors from the source member to various
            destinations.
          items:
            $ref: '#/components/schemas/CorridorSettlementContext'
    SortDirectionEnum:
      type: string
      description: |
        Sort direction for ordered query results:

        - `ASC`: Ascending order (A-Z, 0-9, earliest to latest dates)
        - `DESC`: Descending order (Z-A, 9-0, latest to earliest dates)
      default: DESC
      enum:
        - ASC
        - DESC
    SettlementSortFieldEnum:
      type: string
      default: creationTime
      description: |
        Available fields for sorting settlement lists:

        - `creationTime`: When the settlement was created
        - `settlementAmt`: Settlement amount in source currency
        - `completionTime`: When the settlement was completed (if applicable)
        - `rate`: Exchange rate applied to the settlement
        - `settlementStatus`: Current settlement status
        - `destinationMemberId`: Destination member identifier
        - `settlementId`: Unique settlement identifier
        - `destinationCcy`: Destination currency code
        - `settlementAmtReceived`: Amount received in destination currency
      enum:
        - settlementAmt
        - completionTime
        - settlementAmtReceived
        - destinationMemberId
        - rate
        - settlementStatus
        - settlementId
        - creationTime
        - destinationCcy
    SettlementStatusEnum:
      type: string
      description: >
        Current status of the settlement in the processing lifecycle.


        **Status Flow:**

        1. `S100_SCHEDULED` - Settlement scheduled for future execution

        2. `S200_RECEIVED` - Settlement received and validated, ready for
        processing

        3. `S300_IN_PROGRESS` - Settlement actively being processed

        4. `S400_FIAT_WITHDRAWAL_IN_PROGRESS` - Final fiat currency withdrawal
        in progress


        **Terminal States:**


        5. `S500_TERMINATED` - Settlement cancelled or terminated

        6. `S600_COMPLETED` - Settlement successfully completed

        7. `S700_FAILED` - Settlement failed during processing
      enum:
        - S100_SCHEDULED
        - S200_RECEIVED
        - S300_IN_PROGRESS
        - S400_FIAT_WITHDRAWAL_IN_PROGRESS
        - S500_TERMINATED
        - S600_COMPLETED
        - S700_FAILED
    SettlementResponse:
      type: object
      properties:
        settlementId:
          type: string
          description: Unique settlement identifier.
        settlementStatus:
          $ref: '#/components/schemas/SettlementStatusEnum'
        settlementAmt:
          type: number
          description: Original settlement amount in source currency.
        pendingAmt:
          type: number
          description: Amount still pending processing in source currency.
        rate:
          type: number
          description: >-
            Exchange rate applied to this settlement. This rate was locked when
            the settlement was created.
        settlementAmtReceived:
          type: number
          description: >-
            Actual amount received in destination currency. Populated when
            settlement is completed (S600_COMPLETED status).
        sourceCcy:
          type: string
          pattern: ^[A-Z]{3}$
          description: Source currency code (ISO 4217 3-letter format).
        destinationCcy:
          type: string
          pattern: ^[A-Z]{3}$
          description: Destination currency code (ISO 4217 3-letter format).
        sourceMemberId:
          type: string
          description: Source member identifier.
        destinationMemberId:
          type: string
          description: Destination member identifier.
        notes:
          type: string
          description: Notes or description provided when creating the settlement.
        creationTime:
          type: string
          format: date-time
          description: Timestamp when the settlement was created (ISO 8601 format).
        completionTime:
          type: string
          format: date-time
          description: Timestamp when the settlement was completed (ISO 8601 format).
        dueDate:
          type: string
          format: date-time
          description: >-
            Expected completion date/time for this settlement. Based on
            execution interval and processing time estimates.
    SettlementListResponse:
      type: object
      properties:
        settlements:
          type: array
          description: Array of settlement records matching the query criteria.
          items:
            $ref: '#/components/schemas/SettlementResponse'
        page:
          type: integer
          description: Current page number (0-based)
        size:
          type: integer
          description: Number of records per page. Default is 10, maximum is 100.
        totalPages:
          type: integer
          description: Total number of pages available for the current query
        totalRecords:
          type: integer
          format: int64
          description: Total number of settlement records matching the query criteria.
    SettlementRequest:
      type: object
      description: Request payload for creating a new settlement
      required:
        - destinationMemberId
        - settlementAmt
        - rateId
        - executionInterval
      properties:
        destinationMemberId:
          type: string
          pattern: ^[A-Z0-9_]*$
          description: Unique identifier of the destination member.
        settlementAmt:
          type: number
          format: bigDecimal
          minimum: 0.01
          maximum: 999999999.99
          description: Amount to settle in source currency (e.g., USD).
        rateId:
          type: string
          description: >
            Locked rate identifier obtained from `/v2/settlement-rates`
            endpoint.


            This ID guarantees the exchange rate for this settlement.

            Must be valid and not expired when settlement is created.
        executionInterval:
          $ref: '#/components/schemas/ExecutionIntervalEnum'
        notes:
          type: string
          description: Optional notes or description for this settlement.
  parameters:
    Page:
      name: page
      schema:
        type: integer
        minimum: 0
        default: 0
      in: query
      required: false
      description: |
        Zero-based page number for pagination.
        Use 0 for the first page, 1 for second page, etc.
    Size:
      name: size
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      in: query
      required: false
      description: Number of records per page (default 10, max 100)
    SortDirection:
      name: sortDirection
      schema:
        $ref: '#/components/schemas/SortDirectionEnum'
      in: query
      required: false
      description: |
        Sort direction for ordered results:
        - ASC: Ascending order (A-Z, 0-9, earliest to latest)
        - DESC: Descending order (Z-A, 9-0, latest to earliest)
    SettlementId:
      name: settlement-id
      schema:
        type: string
      in: path
      required: true
      description: Unique settlement identifier (UUID format).
