Receive FX settlement result notification

2023-03-28 11:04

Signature required

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

Field	Data type	Required	Description
exchangeResult	Result object	Yes	Indicates the result of the settlement request. Note: For more details, refer to the Result processing logic chapter.
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. 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	The mode of the settlement. Possible values are: `REALTIME`: Real-time settlement. `APPOINTED`: Appointed settlement. For the full list, refer to the exchangeMode.
exchangeTradeType	String	Yes	Defines the type of settlement. 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 Partner submits `exchangeForwardInfo` field in the request.

Result processing logic

WorldFirst indicates the result of the forward deal in the exchangeResult.resultStatus field. For more information, refer to the result codes section.

After receiving the notification, you need to send a response message to acknowledge the receipt of the notification.

The Partner needs to properly sign the message before making the response. For details, refer to the Sign a request and validate the signature chapter.

The response header observes the following structure:

Signature: Required. Example: Signature: algorithm=RSA256, keyVersion=2, signature=*****
Content-Type: Required. Example: Content-Type: application/json; charset=UTF-8
Client-Id: Required. Example: Client-Id: *****
Response-Time: Required. Example: Response-Time: 2019-04-04T12:08:56+08:00

For more details about the response message, refer to the API overview chapter.

The response body has the following fixed value:

copy
{
  "result":{
     "resultStatus":"S",
     "resultCode":"SUCCESS",
     "resultMessage":"success"
  }
}

In the absense of an ackowledgement reponse from the Partner, WorldFirst will resend the result.

The following policy represents how WorldFirst makes retry attempts:

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

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicates whether this API is called successfully.

Result codes

`exchangeResult.resultCode`

resultCode	resultStatus	resultMessage	Further action
SUCCESS	S	The deal 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.

Samples

Request

Request body sample

copy
{
    "buy": {
        "currency": "USD",
        "value": 231
    },
    "exchangeCreateTime": "2022-05-16T08:55:09Z",
    "exchangeFinishTime": "2022-05-16T08:55:16Z",
    "exchangeId": "*****",
    "exchangeMode": "APPOINTED",
    "exchangeRequestId": "*****",
    "exchangeResult": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "exchangeTradeType": "SPOT",
    "quote": {
        "quoteCurrencyPair": "EUR/USD",
        "quoteExpiryTime": "2022-05-16T09:08:51Z",
        "quoteId": "*****",
        "quotePrice": "1.07461952",
        "quoteStartTime": "2022-05-16T08:53:51Z"
    },
    "sell": {
        "currency": "EUR",
        "value": 215
    }
}

Response

Response header sample

copy
{
"headers": {
  "Content-Type": "application/json",
  "client-id": "*****",
  "response-time": "2022-03-07T07:49:27Z",
  "signature": "algorithm=RSA256,keyVersion=1,signature=VelVji6jp8UJVrBUvZrwij8uPmjc//hfmVJqCCW0x+Yh/HEs5pz9wiMyYLRjykTOii+f5EznxcFIUxPae5KITe3fChufJzFhJ4iku5U/w6exmBWVR5vrvQZSYO0vG5aJKwUQW/jjgaUWg1d+ySmaJ0VZ0pniQRtwYRGCvzdey+gI0+jMFbChIQDemZ0uLCExRQ0SBKAjEH/Vq14KlY88Wr2bR829tqsxaECSq2M5eeDC7j6FGPMazfX1W+EGqa2go2Hif6BnodwXzNsEAfQlUrbwCi9Ey/uNO4ScTX6FVG1nb+q8/k09wTkCz/nHnwTQolDrLRndZqZfz79a344*****"
  }
}

Response body sample

copy
{
  "result":{
     "resultStatus":"S",
     "resultCode":"SUCCESS",
     "resultMessage":"success"
  }
}