Receive association result notification

2023-02-22 10:24

After WorldFirst receives and processes the request of submitting trade orders, we call this API to send out result notifications.

Structure

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

Request body parameters

Field	Data type	Required	Description
notifyRequestId	String	Yes	The notification number of trade submission results defined by WorldFirst More information about this field: This field is an API idempotency field. Maximum length: 64 characters
extRequestId	String	Yes	The request number of trade submission results assigned by the Partner More information about this field: This field is identical to the requestId defined by submitTradeOrder API. Maximum length: 64 characters
associationResult	Result object	Yes	The trade submission result

Request processing

In the request message:

associationResult.resultCode: indicates the trade submission result, see AssociationResult.resultCode section in result code for details.

Note: After the Partner calls submitTradeOrder API, WorldFirst create, associate, and verify trade orders, which are asynchronous operations. In the process, it can not be retrieved by retrying, in the case that the operation fails due to the change of trade or collection order, for example, a collection order is refunded.

The Partner needs to update the order, change the reqeustId, and retry calling submitTradeOrder API to submit the order.

To verify if the message is received, the Partner is required to send the notification to WorldFirst after receiving the requests from it.

Before sending the response message, the request's signature should be valid.

Response header:

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

Sample of the response body

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

WorldFirst resends request notification if the Partner does not send the response message to it. The rule for resending is:

Maximum times of retrying: 7
Interval between two requests: 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, 15 hours.

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Result of API calling

Result code

AssociationResult.resultCode

resultCode	resultStatus	resultMessage	Further action
ASSOCIATION_FAILED	F	Invalid parameter exists (wrong data type, wrong data length, or unspecified parameter).	Update the trade order or its associated information, change order reqeustId, and retry.
		Invalid amount parameter exists.	Update the trade order or its associated information, change order reqeustId, and retry.
		tradeType values are inconsistent for trade orders.	Update the trade order or its associated information, change order reqeustId, and retry.
		Abnormal collection order.	The refunded collection order can not be synchronized in batch or associated. Verify the collection order is in success status.
		Access denied.	The order can not be synchronized in batch or associated. Contact WorldFirst technical support for a specific reason.
		tradeType of a trade order is not supported.	This type of order can not be submitted or associated. Contact WorldFirst technical support for a specific reason.
		Abnormal trade order exists.	The order is abnormal. Contact WorldFirst technical support for a specific reason.
		The number of associated trade orders exceeds the limit.	Update the number of order associations, change order reqeustId, and retry.
		The intended association amount is incorrect.	Update the associated order amount, change order reqeustId, and retry. Note: The submitted order amount can not be modified.
		tradeType values are inconsistent for partial associations of the same collection order.	Update order type, change order reqeustId, and retry.
		An internal system error has occurred. Do not retry.	Contact WorldFirst technical support.
ORDER_SUBMISSION_FAILED	F	Invalid parameter exists (wrong data type, wrong data length, or unspecified parameter).	Update the order or its associated information, change order reqeustId, and retry.
		Invalid amount parameter exists.	Update the order or its associated information, change order reqeustId, and retry.
		tradeType values are inconsistent for trade orders.	Update the order or its associated information, change order reqeustId, and retry.
		Abnormal collection order.	The refunded collection order can not be synchronized in batch or associated. Verify if it is in the status of success.
		Access denied.	The order can not be synchronized in batch or associated. Contact WorldFirst technical support for a specific reason.
		tradeType of a trade order is not supported.	This type of order can not be submitted or associated. Contact WorldFirst technical support for a specific reason.
		Abnormal trade order exists.	The order is abnormal. Contact WorldFirst technical support for a specific reason.
		The number of associated trade orders exceeds the limit.	Update the number of order associations, change order reqeustId, and retry.
		The intended association amount is incorrect.	Update the associated order amount, change order reqeustId, and retry. Note: The submitted order amount can not be modified.
		tradeType values are inconsistent for partial associations of the same collection order.	Update order type, change order reqeustId, and retry.
		An internal system error has occurred. Do not retry.	Contact WorldFirst technical support.
VERIFICATION_DENIED	F	The verification has been denied.	The order synchronization fails. The order update is denied. Contact WorldFirst technical support.
ADDITIONAL_FILE_NEEDED	F	An additional file is needed for the verification.	An additional file is in need of order association. Log in WorldFirst and provide supplemental materials manually.
VERIFICATION_PASSED	S	The verification has passed.

Result.resultCode

resultCode	resultStatus	resultMessage
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do not retry.
PARAM_ILLEGAL	F	Illegal parameters exist. For example, a non-numeric input, or an invalid date.
INVALID_API	F	The called API is invalid or not active.
INVALID_CLIENT	F	The client is invalid.
INVALID_SIGNATURE	F	The signature is invalid.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.
UNKNOWN_EXCEPTION	U	The API call fails, which is caused by unknown reasons.

Sample code

Request

copy
{
  "associationResult": {
    "resultCode": "*****",
    "resultMessage": "****",
    "resultStatus": "S"
  },
  "extRequestId": "****",
  "notifyRequestId": "****"
}

Response

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