Create a Settlement

Initiates an FX settlement to exchange currencies. For SPOT settlements, provide a valid quoteId obtained from the quotation API. For FORWARD and UNFUNDED_SPOT settlements, provide a dealId along with the sell or buy amount. The requestId enables idempotent submission to prevent duplicate settlements.
Request Parameters
requestIdstring
required
A unique identifier for idempotency. Reusing the same value safely prevents duplicate settlement submissions.
dealIdstring
The deal identifier to settle against. Required for FORWARD and UNFUNDED_SPOT settlements; must not be provided for SPOT settlements.
quoteIdstring
The quote identifier to settle against. Required for SPOT settlements only.
sellAmountAmount
The amount of currency to sell. Required only for FORWARD and UNFUNDED_SPOT deal with partial settlements, either sellAmount or buyAmount must be provided.
buyAmountAmount
The amount of currency to buy. Required only for FORWARD and UNFUNDED_SPOT with partial settlements, either buyAmount or sellAmount must be provided.
settlementDatestring
The expected settlement date in YYYY-MM-DD format (UTC). Applicable to FORWARD and UNFUNDED_SPOT settlements.
beneficiaryBeneficiary
The beneficiary information for the payout. Provide this only when the settlement involves a payout to a bank account.
Show child parametersShow child parameters
referencestring
A business reference number for tracking and reconciliation purposes.
memostring
An optional remark or note attached to the transaction.
Response Parameters
resultResult
See Result.
idstring
The unique settlement identifier.
requestIdstring
Echoes the requestId submitted in the request.
sellAmountAmount
The sold amount.
buyAmountAmount
The bought amount.
quoteQuote
The quote details associated with this settlement.
Show child parametersShow child parameters
dealIdstring
The deal identifier, present for FORWARD and UNFUNDED_SPOT settlements.
settlementDatestring
The expected settlement date in YYYY-MM-DD format (UTC).
beneficiaryBeneficiary
The beneficiary information, if applicable.
Show child parametersShow child parameters
referencestring
The business reference number provided in the request.
memostring
The transaction remark provided in the request.
feeAmountAmount
The fee amount charged for the settlement.
statusstring
The current status of the settlement. Supported values: - PROCESSING — Settlement is being processed. - SUCCESS — Settlement completed successfully. - FAILED — Settlement failed.
createdAtdatetime
The timestamp when the settlement was created, in ISO 8601 format.
settledAtdatetime
The timestamp when the settlement was completed, in ISO 8601 format.
failedAtdatetime
The timestamp when the settlement failed, in ISO 8601 format. Only present when status is FAILED.
failureCodestring
The failure code indicating the reason for failure. Only present when status is FAILED.
failureMessagestring
A human-readable description of the failure. Only present when status is FAILED.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSsuccessN/A
FX_SETTLEMENT_DATE_NOT_SUPPORTEDFThe requested settlement date is not supported.Select a valid settlement date within the supported range.
FX_QUOTE_EXPIREDFThe quote has expired.Obtain a new quote and retry the settlement request.
FX_SETTLEMENT_INCONSISTENT_WITH_DEAL_ORDERFThe settlement details are inconsistent with the deal order.Verify that sell/buy amounts and currencies match the deal.
FX_SETTLEMENT_METHOD_NOT_SUPPORTEDFThe settlement method is not supported.Verify the settlement type and parameters.
FX_SETTLEMENT_BENEFICIARY_NOT_EXISTEDFThe specified beneficiary does not exist.Verify the beneficiary ID and account type.
FX_SETTLEMENT_AMOUNT_EXCEED_DEAL_AMOUNTFThe settlement amount exceeds the deal amount.Reduce the settlement amount to be within the remaining deal limit.
REPEAT_REQ_INCONSISTENTFInconsistent parameters for repeated requests.Recheck the request parameters.
Definition
POST /api/open/v1/fx/settlements/create
Request
{
"requestId": "SR20260402001",
"quoteId": "QT202604021208001"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "STL20260402001",
"requestId": "SR20260402001",
"sellAmount": {
  "currency": "USD",
  "value": 10000
},
"buyAmount": {
  "currency": "HKD",
  "value": 77850
},
"quote": {
  "quoteId": "QT202604021208001",
  "currencyPair": "USD/HKD",
  "clientRate": 7.785,
  "effectiveAt": "2026-04-02T04:08:56Z",
  "expiresAt": "2026-04-02T04:09:56Z"
},
"status": "SUCCESS",
"createdAt": "2026-04-02T04:08:58Z",
"settledAt": "2026-04-02T04:08:58Z"
}