Skip to content
API Reference
/
/Settlement

Almond Settlement API (1.1.0)

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.

System Flow
Figure: Settlement Flow

Download OpenAPI description
settlements.json
settlements.yaml
Overview
URL
https://www.almondfintech.com/contact-us
Almond Fintech API Support
info@almondfintech.com
License
Copyright © 2025 Almond FinTech. All rights reserved.
Languages
Servers
Mock server
https://docs.almondfintech.com/_mock/apis/settlements
Sandbox
https://api.sandbox.almondfintech.com
Production
https://api.almondfintech.com

Settlement Rate

Operations

Settlement Context

Operations

Settlement

Operations

Create Settlement

Request

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
Bodyapplication/jsonrequired
destinationMemberIdstring^[A-Z0-9_]*$required

Unique identifier of the destination member.

settlementAmtnumber(bigDecimal)[ 0.01 .. 999999999.99 ]required

Amount to settle in source currency (e.g., USD).

rateIdstringrequired

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.

executionIntervalstring(ExecutionIntervalEnum)required

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"
notesstring

Optional notes or description for this settlement.

curl -i -X POST \
  https://docs.almondfintech.com/_mock/apis/settlements/v2/settlements \
  -H 'Content-Type: application/json' \
  -d '{
    "destinationMemberId": "DEST_MEMBER_1",
    "settlementAmt": 1500,
    "rateId": "c162d93e-dfac-4d26-8da3-b3b76f8ca3e0",
    "executionInterval": "ONE_HOUR",
    "notes": "test settlement"
  }'

Responses

Settlement created successfully

Bodyapplication/json
settlementIdstring

Unique settlement identifier.

settlementStatusstring(SettlementStatusEnum)

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:

  1. S500_TERMINATED - Settlement cancelled or terminated
  2. S600_COMPLETED - Settlement successfully completed
  3. 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"
settlementAmtnumber

Original settlement amount in source currency.

pendingAmtnumber

Amount still pending processing in source currency.

ratenumber

Exchange rate applied to this settlement. This rate was locked when the settlement was created.

settlementAmtReceivednumber

Actual amount received in destination currency. Populated when settlement is completed (S600_COMPLETED status).

sourceCcystring^[A-Z]{3}$

Source currency code (ISO 4217 3-letter format).

destinationCcystring^[A-Z]{3}$

Destination currency code (ISO 4217 3-letter format).

sourceMemberIdstring

Source member identifier.

destinationMemberIdstring

Destination member identifier.

notesstring

Notes or description provided when creating the settlement.

creationTimestring(date-time)

Timestamp when the settlement was created (ISO 8601 format).

completionTimestring(date-time)

Timestamp when the settlement was completed (ISO 8601 format).

dueDatestring(date-time)

Expected completion date/time for this settlement. Based on execution interval and processing time estimates.

Response
application/json
{
  "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"
}

Get Settlements

Request

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
Query
pageinteger>= 0

Zero-based page number for pagination. Use 0 for the first page, 1 for second page, etc.

Default 0
sizeinteger[ 1 .. 100 ]

Number of records per page (default 10, max 100)

Default 10
sortDirectionstring(SortDirectionEnum)

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)
Default "DESC"
Enum"ASC""DESC"
sortFieldstring(SettlementSortFieldEnum)

Field to sort settlements

Default "creationTime"
Enum"settlementAmt""completionTime""settlementAmtReceived""destinationMemberId""rate""settlementStatus""settlementId""creationTime""destinationCcy"
destinationMemberIdstring^[A-Z0-9_]*$

Filter settlements for this specific destination member.

Example: destinationMemberId=DEST_MEMBER_1
settlementStatusstring(SettlementStatusEnum)

Filter settlements by current status

Enum"S100_SCHEDULED""S200_RECEIVED""S300_IN_PROGRESS""S400_FIAT_WITHDRAWAL_IN_PROGRESS""S500_TERMINATED""S600_COMPLETED""S700_FAILED"
createdAfterstring(date-time)

Filter settlements created after this timestamp. Uses ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Useful for retrieving only recent settlements.

Example: createdAfter=2024-01-01T00:00:00Z
curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/settlements/v2/settlements?page=0&size=10&sortDirection=ASC&sortField=settlementAmt&destinationMemberId=DEST_MEMBER_1&settlementStatus=S100_SCHEDULED&createdAfter=2024-01-01T00%3A00%3A00Z'

Responses

Successful response

Bodyapplication/json
settlementsArray of objects(SettlementResponse)

Array of settlement records matching the query criteria.

pageinteger

Current page number (0-based)

sizeinteger

Number of records per page. Default is 10, maximum is 100.

totalPagesinteger

Total number of pages available for the current query

totalRecordsinteger(int64)

Total number of settlement records matching the query criteria.

Response
application/json
{
  "settlements": [
    { … }
  ],
  "page": 0,
  "size": 10,
  "totalPages": 1,
  "totalRecords": 1
}

Get Settlement

Request

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
Path
settlement-idstringrequired

Unique settlement identifier (UUID format).

curl -i -X GET \
  'https://docs.almondfintech.com/_mock/apis/settlements/v2/settlements/{settlement-id}'

Responses

Settlement Response

Bodyapplication/json
settlementIdstring

Unique settlement identifier.

settlementStatusstring(SettlementStatusEnum)

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:

  1. S500_TERMINATED - Settlement cancelled or terminated
  2. S600_COMPLETED - Settlement successfully completed
  3. 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"
settlementAmtnumber

Original settlement amount in source currency.

pendingAmtnumber

Amount still pending processing in source currency.

ratenumber

Exchange rate applied to this settlement. This rate was locked when the settlement was created.

settlementAmtReceivednumber

Actual amount received in destination currency. Populated when settlement is completed (S600_COMPLETED status).

sourceCcystring^[A-Z]{3}$

Source currency code (ISO 4217 3-letter format).

destinationCcystring^[A-Z]{3}$

Destination currency code (ISO 4217 3-letter format).

sourceMemberIdstring

Source member identifier.

destinationMemberIdstring

Destination member identifier.

notesstring

Notes or description provided when creating the settlement.

creationTimestring(date-time)

Timestamp when the settlement was created (ISO 8601 format).

completionTimestring(date-time)

Timestamp when the settlement was completed (ISO 8601 format).

dueDatestring(date-time)

Expected completion date/time for this settlement. Based on execution interval and processing time estimates.

Response
application/json
{
  "settlements": [
    { … }
  ]
}
Copyright © 2025 Almond FinTech. All rights reserved.