WorldFirst DocsWorldFirst DocsDOCS

Create an FX settlement

POST: /asmin/api/v1/business/fund/createExchange Signature required

The Partner can use this API to create a settlement.

The createExchange API supports the following currency settlement scenarios:

  • Create a settlement with forward rates:
    • For this scenario, the process is asynchronous. WorldFirst responds to the Partner that the settlement is being processed, rather than the final result of the settlement. To query the forward deal result, a Partner can utilize the inquiryExchange interface. WorldFirst sends the notification about the settlement result with the notifyExchange interface.
  • Create a settlement with spot rates
    • For this scenario, the process is synchronous. WorldFirst returns the result of the settlement in the response message.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field

Data type

Required

Description

customerId

String

Yes(Conditional)

The unique id that is assigned by WorldFirst to identify an account.

Note:

  • customerId and accessToken cannot be both empty.

More information:

  • Maximum length: 64 characters

accessToken

String

Yes(Conditional)

The access token that is used for OAuth authorization.

Note:

  • customerId and accessToken cannot be both empty.

More information:

  • Maximum length: 64 characters

exchangeRequestId

String

Yes

The unique ID that is assigned by the Partner to identify a settlement request.

Note:

  • This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 128 characters

quote

Quote object

Yes(Conditional)

The quote information.

Note:

  • This field is required when the quote is locked-in.

sell

QuoteAmount object

Yes

The amount and the currency to be sold.

More information:

  • sell.value and buy.value cannot both be empty.

buy

QuoteAmount object

Yes

The amount and the currency to be bought.

More information:

  • sell.value and buy.value cannot both be empty.

exchangeMode

String

Yes

Defines the mode of the settlement request, which could be either in real-time, or at an appointed time.

Possible values are:

  • REALTIME
  • APPOINTED

For the full list, refer to the exchangeMode.

exchangeTradeType

String

Yes

Defines the type that the settlement trades in.

Possible values are:

  • SPOT: Using spot rate.
  • FORWARD: Using forward rate.

For the full list, refer to the exchangeTradeType.

exchangeForwardInfo

ExchangeForwardInfo object

Yes(Conditional)

Information about the forward exchange.

Note:

  • This field is required when the exchangeTradeType field is FORWARD.

exchangeOrderAddition

ExchangeQuoteAddition object

No

Additional information that is attached to the settlement request, such as the ID of the reference order.

exchangeRequestTime

String

No

The time of the settlement request.

Notes:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

Response parameters

Field

Data type

Required

Description

result

Result object

Yes

Indicates whether this API is called successfully.

exchangeId

String

Yes

The unique ID that is assigned by WorldFirst to identify a settlement request.

More information:

  • Maximum length: 64 characters

exchangeRequestId

String

Yes

The unique ID that is assigned by the Partner to identify a settlement request.

Note:

  • This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 128 characters

sell

QuoteAmount object

Yes

The amount and the currency to be sold.

buy

QuoteAmount object

Yes

The amount and the currency to be bought.

exchangeCreateTime

Datetime object

Yes

The time that the settlement request is created.

Notes:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

exchangeFinishTime

Datetime object

Yes

The time that the settlement request is completed.

Notes:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00, or 2019-01-01T01:01:01Z(UTC timezone).

quote

Quote object

Yes

Transfer quote information.

exchangeMode

String

Yes

Defines the mode of the settlement request, which could be either in real-time, or at an appointed time.

Possible values are:

  • REALTIME
  • APPOINTED

For the full list, refer to the exchangeMode.

exchangeTradeType

String

Yes

Defines the type that the settlement trades in.

Possible values are:

  • SPOT: Using spot rate.
  • FORWARD: Using forward rate.

For the full list, refer to the exchangeTradeType.

exchangeForwardInfo

ExchangeForwardInfo object

Yes(Conditional)

Information about the forward exchange.

Note:

  • This field is required when the exchangeTradeType field is FORWARD.

Result processing logic

After calling the API, a response is returned. The possible responses for result.resultStatus are:

Result status

Description

S

This indicates the API call succeeded.

For the settlements with forward rates:

  • If result.resultStatus is S, this result status indicates that WorldFirst accepts the request and is processing the settlement.
  • For the result of the settlement, the Partner can call the inquiryExchange interface or wait for the notification from the notifyExchange interface.

For the settlements with on-spot rates:

  • This indicates the settlement request succeeded.

F

This indicates the API call failed. For more information on why the call failed, see result.resultCode.

U

This indicates the API call result is unknown. Call the inquiryExchange API to check the exchange status.

Result codes

result.resultCode

System-related result codes

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

The spot settlement has been completed successfully.

PROCESSING

S

The settlement is being processed.

This result code is for the forward settlement only.

Call the inquiryExchange API for the settlement result or wait for notifications.

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue.

UNKNOWN_EXCEPTION

U

API failed due to unknown reason.

The service might be down, retry later. If the issue persists, contact our Technical Support Team.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

Call the interface again to resolve the issue. If the issue persists, contact our Technical Support Team.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API is being called.

INVALID_CLIENT

F

The client is invalid.

The Client ID does not exist or is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

Make sure the request is properly signed with a valid signature.

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

Business-related result codes

resultCode

resultStatus

resultMessage

Further action

BALANCE_INSUFFICIENT

F

The balance is insufficient for the exchange.

This result code is for settlements with on-spot rates only.

Make sure the balance is sufficient and try again.

INVALID_ACCESS_TOKEN

F

Invalid access token

Check whether the accessToken is correct.

UN_SUPPORT_BUSINESS

F

Unsupported business.

Invalid parameters are used e.g. currency is incorrect. Retry with the correct information.

QUOTE_EXPIRED

F

The quote is expired.

Call the createQuote API to create a new quote. Retry creating a new settlement request with the new quote.

FX_RELATED_ORDER_NOT_EXIST

F

The exchange order does not exist.

This result code is for forward settlements only. Make sure the dealId is correct and try again.

CURRENCY_NOT_SUPPORT

F

The currency is not supported.

Make sure the currency input is correct and try again.

CONTRACT_CHECK_FAIL

F

The contract check has failed.

Check the contract status before retrying.

Samples

Request

Request body sample

On-spot rate scenario

copy
{
  "customerId": "*****",
  "exchangeRequestId": "*****",
  "sell": {
    "currency": "EUR",
    "value": 23333
  },
  "buy": {
    "currency": "GBP",
    "value": 19601
  },
  "exchangeMode": "APPOINTED",
  "exchangeTradeType": "SPOT",
  "exchangeOrderAddition": {
    "referenceOrderId": "*****",
    "exchangeMemo": ""
  },
  "exchangeRequestTime": "{{$isoTimestamp}}",
  "quote": {
    "quoteCurrencyPair": "EUR/GBP",
    "quoteExpiryTime": "2022-08-25T10:17:08Z",
    "quoteId": "*****",
    "quotePrice": "0.84005",
    "quoteStartTime": "2022-08-25T10:16:38Z"
  }
}

Forward rate scenario

copy
{
  "customerId": "*****",
  "exchangeRequestId": "*****",
  "sell": {
    "currency": "USD",
    "value": 1000
  },
  "buy": {
    "currency": "EUR",
    "value": 995
  },
  "exchangeMode": "APPOINTED",
  "exchangeTradeType": "FORWARD",
  "exchangeOrderAddition": {
    "exchangeMemo": "exchange-test",
    "referenceOrderId": "*****"
  },
  "exchangeRequestTime": "2022-06-28T02:58:47Z",
  "exchangeForwardInfo": {
    "dealId": "*****"
  }
}

Request calling samples

copy
var jsonStr="{\"customerId\":\"*****\",\"exchangeRequestId\":\"*****\",\"sell\":{\"currency\":\"EUR\",\"value\":215},\"buy\":{\"currency\":\"USD\",\"value\":231},\"exchangeMode\":\"APPOINTED\",\"exchangeTradeType\":\"SPOT\",\"exchangeOrderAddition\":{\"referenceOrderId\":\"*****\",\"exchangeMemo\":\"exchange-test-memo\"},\"exchangeRequestTime\":\"2022-05-16T08:55:08Z\",\"quote\":{\"quoteCurrencyPair\":\"EUR/USD\",\"quoteExpiryTime\":\"2022-05-16T09:08:51Z\",\"quoteId\":\"*****\",\"quotePrice\":\"1.07461952\",\"quoteStartTime\":\"2022-05-16T08:53:51Z\"}}";
var client = new RestClient("http://{domain_name}.com/amsin/api/v1/business/fund/createExchange");
var request = new RestRequest(Method.POST);
request.AddHeader("client-id","*****");
request.AddHeader("request-time","2022-05-17T11:19:20+08:00");
request.AddHeader("Content-Type","application/json");
request.AddHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
request.AddParameter("application/json; charset=utf-8", jsonStr, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
copy
url = "http://{domain_name}.com//amsin/api/v1/business/account/createExchange"
headers = {
    "client-id": "*****",
    "request-time": "2022-05-17T11:19:20+08:00",
    "Content-Type": "application/json",
    "signature": "algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****"
}
datas ={"customerId":"*****","exchangeRequestId":"*****","sell":{"currency":"EUR","value":215},"buy":{"currency":"USD","value":231},"exchangeMode":"APPOINTED","exchangeTradeType":"SPOT","exchangeOrderAddition":{"referenceOrderId":"*****","exchangeMemo":"exchange-test-memo"},"exchangeRequestTime":"2022-05-16T08:55:08Z","quote":{"quoteCurrencyPair":"EUR/USD","quoteExpiryTime":"2022-05-16T09:08:51Z","quoteId":"*****","quotePrice":"1.07461952","quoteStartTime":"2022-05-16T08:53:51Z"}}
res = requests.post(url=url, data=json.dumps(datas), headers=headers)
copy
CloseableHttpClient client = HttpClientBuilder.create().build();
HttpPost httpPost = new HttpPost("http://{domain_name}.com//amsin/api/v1/business/fund/createExchange");
httpPost.addHeader("client-id", "*****");
httpPost.addHeader("request-time", "2022-05-17T11:19:20+08:00");
httpPost.addHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****" );
httpPost.addHeader("Content-Type","application/json");
StringEntity entity = new StringEntity("{\"customerId\":\"*****\",\"exchangeRequestId\":\"*****\",\"sell\":{\"currency\":\"EUR\",\"value\":215},\"buy\":{\"currency\":\"USD\",\"value\":231},\"exchangeMode\":\"APPOINTED\",\"exchangeTradeType\":\"SPOT\",\"exchangeOrderAddition\":{\"referenceOrderId\":\"*****\",\"exchangeMemo\":\"exchange-test-memo\"},\"exchangeRequestTime\":\"2022-05-16T08:55:08Z\",\"quote\":{\"quoteCurrencyPair\":\"EUR/USD\",\"quoteExpiryTime\":\"2022-05-16T09:08:51Z\",\"quoteId\":\"*****\",\"quotePrice\":\"1.07461952\",\"quoteStartTime\":\"2022-05-16T08:53:51Z\"}}");
httpPost.setEntity(entity);
CloseableHttpResponse response = client.execute(httpPost);
copy
var jsonStr="{\"customerId\":\"*****\",\"exchangeRequestId\":\"*****\",\"sell\":{\"currency\":\"EUR\",\"value\":215},\"buy\":{\"currency\":\"USD\",\"value\":231},\"exchangeMode\":\"APPOINTED\",\"exchangeTradeType\":\"SPOT\",\"exchangeOrderAddition\":{\"referenceOrderId\":\"*****\",\"exchangeMemo\":\"exchange-test-memo\"},\"exchangeRequestTime\":\"2022-05-16T08:55:08Z\",\"quote\":{\"quoteCurrencyPair\":\"EUR/USD\",\"quoteExpiryTime\":\"2022-05-16T09:08:51Z\",\"quoteId\":\"*****\",\"quotePrice\":\"1.07461952\",\"quoteStartTime\":\"2022-05-16T08:53:51Z\"}}";
var client = "http://{domain_name}.com/amsin/api/v1/business/fund/createExchange";
var xhr = new XMLHttpRequest;
xhr.open("POST",client,true);
xhr.setRequestHeader("client-id","*****");
xhr.setRequestHeader("request-time","2022-05-17T11:19:20+08:00");
xhr.setRequestHeader("Content-Type","application/json");
xhr.setRequestHeader("signature","algorithm=RSA256,keyVersion=1,signature=RckSOIrxy%2FKqC%2FZQOO0t74U9U4TFVYKmW%2FZflFRut7W1hipos3NLBGdpzbulcc5Q7XwZP1t3qgTZMFrC%2FlzOQCOsBhUgelvEAuACu49PEGiAus8sU%2FFJa1HOIUmst3oWjLT%2BDqY083mR7jVwc5O2JYP08wNCLu55PFZtXHBUfwEAYoZInhgRoLtQTr%2F7Bphd7L9cS3xD3tluxbgkcaFr7NQVrfWJuQKp%2BFrabo6xZr%2FRHZRd%2FijALuUYYjXH92n4VFwSXSO%2B%2BUBVPoGyWWz1q3QJ2tHNVU7wpc3wtCwwB76pNfGTbJit%2BdylGU8O5UkW3TwSkNnpzepRABM8bBQpgQ%*****");
xhr.send(jsonStr);

Response

Response body sample

On-spot rate scenario

copy
{
  "buy": {
    "currency": "GBP",
    "value": 19601
  },
  "exchangeCreateTime": "2022-08-25T10:16:49Z",
  "exchangeFinishTime": "2022-08-25T10:16:57Z",
  "exchangeId": "*****",
  "exchangeMode": "APPOINTED",
  "exchangeRequestId": "*****",
  "exchangeTradeType": "SPOT",
  "quote": {
    "quoteCurrencyPair": "EUR/GBP",
    "quoteExpiryTime": "2022-08-25T10:17:08Z",
    "quoteId": "*****",
    "quotePrice": "0.84005",
    "quoteStartTime": "2022-08-25T10:16:38Z"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "sell": {
    "currency": "EUR",
    "value": 23333
  }
}

Forward rate scenario

copy
{
  "customerId": "*****",
  "exchangeRequestId": "*****",
  "sell": {
    "currency": "CNH",
    "value": 1000
  },
  "buy": {
    "currency": "EUR"
  },
  "exchangeMode": "APPOINTED",
  "exchangeTradeType": "FORWARD",
  "exchangeOrderAddition": {
    "referenceOrderId": "*****",
    "exchangeMemo": "*****"
  },
  "exchangeRequestTime": "2022-08-26T10:16:57Z",
  "exchangeForwardInfo": {
    "dealId": "*****"
  }
}

@2024 WorldFirst