Receive FX settlement result notificationSignature required

2024-12-03 08:45

After the settlement is completed, WorldFirst notifies the Partner with this API of the result. The Partner needs to process the result and response to WorldFirst indicating the reception of the given notification.

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

exchangeResult Result REQUIRED

Indicates the result of the settlement request.

For more details, refer to the Result processing logic section on this page.

Show child parameters

exchangeId String REQUIRED

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

More information:

Maximum length: 64 characters

exchangeRequestId String REQUIRED

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

More information:

This field is an API idempotency field.For details about API idempotency, see the Idempotency chapter.
Maximum length: 128 characters

sell QuoteAmount REQUIRED

The amount and the currency to be sold.

Show child parameters

buy QuoteAmount REQUIRED

The amount and the currency to be bought.

Show child parameters

exchangeCreateTime DateTime CONDITIONAL

The time that the settlement request is created.

This parameter is only returned when the exchangeRequestTime parameter is specified in the createExchange API.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

exchangeFinishTime DateTime REQUIRED

The time that the settlement request is completed.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

quote Quote REQUIRED

Transfer quote information.

Show child parameters

exchangeMode String REQUIRED

The mode of the settlement.

Valid values are:

REALTIME: indicates an exchange rate at the real-time.
APPOINTED: indicates an exchange rate at the appointed time.

exchangeTradeType String REQUIRED

Defines the type of settlement.

Valid values are:

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

exchangeUnfundedInfo ExchangeForwardInfo CONDITIONAL

Information about the forward exchange.

This field is returned only when the value of result.resultStatus is S and the value of exchangeTradeType is UNFUNDED_SPOT.

Show child parameters

exchangeForwardInfo ExchangeForwardInfo CONDITIONAL

Information about the forward exchange.

This field is returned only when the value of result.resultStatus is S and the value of exchangeTradeType is FORWARD.

Show child parameters

Response parameters

result Result REQUIRED

Indicates whether this API is called successfully.

Show child parameters

API Explorer

Request

Request Body

Response

Response Body

Result processing logic

WorldFirst sends you the result of the forex settlement with the exchangeResult.result parameter in the request. For details, see the following exchangeResult.resultCode section. After receiving the result notification, you need to send a response to acknowledge the reception of the notification.

Note: You must sign the message before making the response. Take the following header codes as an example. For details, see the "Sign a request and validate the signature " chapter and the Response header chapter.

Sample Code

If you do not send the acknowledgment back toWorldFirst, WorldFirst retries to send the result by complying with the following attempt rules:

WorldFirst retries notifications 7 times at most.
Intervals between notifications: 2m, 10m, 10m, 1h, 2h, 6h, and 15h.

exchangeResult.resultCode

Code	Value	Message	Further action
SUCCESS	S	The settlement is successfully completed.
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.

result.resultCode

Code	Value	Message	Further action
SUCCESS	S	Success
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.