DOCS

Submit trade order

POST: /amsin/api/v1/business/account/submitTradeOrder

This API is used to submit trade orders. The Partner calls submitAttachment API to submit the required attachments.

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

requestId

String

Yes

The unique ID assigned by the Partner to identify a trade order submission request.

More information about this field:

  • This field is an API idempotency field. The Partner can use it to do the idempotent check.
  • Maximum length: 64 characters

sceneCode

String

Yes

The code that represents the business scenario. Valid values:

  • CREATE_B2B_ORDERS: the B2B trade orders are created and associated.
  • PAY_INTO_CHINA: applied to the foreign exchange scenario without the association of the trade order.

quotaAccumulationMethod

String

Yes

The method that is used for the quota accumulation. Valid values are:

  • USER_ID: indicates the quota is accumulated by the WorldFirst user ID.
  • BATCH_NO: indicates the quota is accumulated by the batch number of trade orders.
  • RECEIVING_ACCOUNT: indicates the quota is accumulated by the receiving account.
  • VIRTUAL_ACCOUNT: indicates the quota is accumulated by the virtual account.
  • BENEFICIARY: indicates the quota is accumulated by the beneficiary.
  • TRANSFER_ID: indicates the quota is accumulated by the transfer ID.
  • COLLECTION_ID: indicates the quota is accumulated by the collection ID.

quotaAccumulationId

String

Yes

The ID that is used for the quota accumulation. Specify this parameter with the following rules:

  • If quotaAccumulationMethod = USER_ID, specify this parameter as the WorldFirst user ID.
  • If quotaAccumulationMethod = RECEIVING_ACCOUNT, specify this parameter as the receiving account.
  • If quotaAccumulationMethod = VIRTUAL_ACCOUNT , specify this parameter as the virtual account.
  • If quotaAccumulationMethod = BENEFICIARY , specify this parameter as the beneficiary ID.
  • If quotaAccumulationMethod = BATCH_NO , specify this parameter as the batch number, which is specified in the referenceBatchNo parameter.
  • If quotaAccumulationMethod = TRANSFER_NO , specify this parameter as the transfer ID.
  • If quotaAccumulationMethod = COLLECTION_NO , specify this parameter as the batch number, which is specified in the collection ID.

tradeOrders

Array <TradeOrder Object>

Yes

The list of trade orders. Specify this parameter with the following rules:

  • If the value of the sceneCode parameter is CREATE_B2B_ORDERS, the maximum size of this parameter is 10 elements.
  • If the value of the sceneCode parameter is PAY_INTO_CHINA, the maximum size of this parameter is 100 elements.

platformOnly for B2C

String

No (Conditional)

The platform where the trade order occurs. Specify this parameter if he value of the sceneCode parameter is PAY_INTO_CHINA.

More information about this parameter:

  • Maximum length: 32 characters

notifyUrl

String

String

No

The asynchronous URL where the notification of trade order submission result is sent.

More information about this field:

  • Maximum length: 256 characters

Response parameters

Field

Data type

Required

Description

result

Result Object

Yes

Indicates the result of trade order submission.

requestId

String

Yes

The unique ID assigned by the Partner to identify a trade order submission request.

More information about this field:

  • This field is an API idempotency field. The Partner can use it to do the idempotent check.
  • Maximum length: 64 characters

acceptOrderId

Only for B2B

String

No

Accepted order number. Specify this parameter if sceneCode = CREATE_B2B_ORDERS.

More information about this field:

  • Maximum length: 128 characters

tradeOrderResult

Only for B2C

Array <TradeOrderResult object> 

Conditional

The trade order information, including the trade order number and the trade order status. This parameter is returned if the value of the sceneCode parameter is PAY_INTO_CHINA. 

Result processing logic

Once the Partner calls API, WorldFirst returns with its result. The range of result.resultStatus field is:

result.resultStatus

Description

S

API is called with success.

F

API is called with failure.

For reasons, refer to result.resultCode and result.resultMessage.

U

When API returns with UNKNOWN, retry calling it.

Retry strategy:

  • Maximum times of retrying: 7
  • Interval of retrying: 5 minutes, 10 minutes, 20 minutes, 40 minutes, 80 minutes, 160 minutes, 320 minutes.

Please contact WorldFirst technical support if the issue remains.

Result code

result.resultCode

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do Not retry.

Contact WorldFirst technical support for human intervention.

PARAM_ILLEGAL

F

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

Update the trade order, change requestId, and retry it.

INVALID_SIGNATURE

F

The signature is invalid.

Validate the signing request, change requestId, and retry it.

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

It's a idempotent request. Do Not retry.

UNKNOWN_EXCEPTION

U

The API call is failed, which is caused by unknown reasons.

Do not change requestId. Retry it.

FUND_ORDER_NOT_EXIST

F

The fund order does not exit.

Contact WorldFirst technical support.

ACCESS_DENIED

F

Access is denied for submitting trade orders.

Contact WorldFirst technical support.

ORDER_COUNT_EXCEED_LIMIT

F

The number of associated trade orders exceeds the limit.

Update the number of order associations, change order reqeustId, and retry it.

WRONG_TRADE_TYPE

F

tradeType is not supported, or tradeType values are inconsistent across trade orders.

Contact WorldFirst technical support.

REQUEST_PARAM_AMOUNT_ERROR

F

Invalid amount parameter exists.

Update the trade order or its associated details, change the order reqeustId, and retry it.

TRADE_ORDER_AUTH_STATUS_ILLEGAL

F

The associated trade order already exists, and its verification has not passed.

Contact WorldFirst technical support.

RELATE_AMOUNT_ERROR

F

The intended association amount is incorrect.

Update the associated amount of trade order, change order reqeustId, and retry.

Note: The amount of the submitted order can not be modified.

ENTITY_REGISTRATION_REQUIRED

F

Entity registration is required for uploading customs declarations.

Contact WorldFirst technical support.

INCONSISTENT_TRADE_TYPE

F

tradeType values are inconsistent for partial associations of the same collection order.

Contact WorldFirst technical support.

UN_SUPPORT_BUSINESS

F

Unsupported business.

Invalid parameter. Retry with the correct parameters.

CONTRACT_CHECK_FAIL

F

The contract check has failed.

Check the contract status then retry.

REGULATED_COUNTRY_NOT_SUPPORTEDFThe tradeCountry or deliverCountry of the trade order is not supported. We do not support the order temporarily for the safety of customers' funds.

For the full list of regulated countries, refer to the parameter introduction . Please contact WorldFirst Support Team for further details. 

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

Ensure all the fields in the requests are the same and try again.

Sample code

Sample 1: B2C senario where the value of quotaAccmulationMethod is USER_ID

Request

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "USER_ID",
    "quotaAccumulationId": "21201200791*****",
    "platform": "AE",
    "tradeOrder": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderTime": "2023-01-10T21:18:24Z",
            "payTime": "2023-01-10T21:28:24Z",
            "orderType": "LOAN",
            "tradeType": "GOODS",
            "tradeAmount": {
                "value": 500,
                "currency": "USD"
            },
            "transAmount": {
                "value": 500,
                "currency": "USD"
            },
            "merchant": {
                "store": {
                    "storeShopUrl": "//www.aliexpress.com/store/56*****"
                }
            },
            "buyer": {
                "referenceBuyerId": "7175*****",
                "buyerName": {
                    "fullName": "ekaterina tsip*****"
                }
            },
            "goods": [
                {
                    "goodsName": "*****",
                    "goodsCategory": "Jewelry & Access*****",
                    "goodsQuantity": "1"
                }
            ],
            "shipping": {
                "wayBillInfo": [
                    {
                        "shippingOrderReferenceNo": "RM450941*****",
                        "shippingAddress": {
                            "address1": "Калининград г, Калининградская обл, Менделее*****",
                            "city": "Калининг*****",
                            "region": "RU"
                        }
                    }
                ]
            }
        }
    ]
}

Response

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
    },
    "requestId": "20230222191210001100300007*****",
    "tradeOrderResults": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderStatus": "ACCEPT",
            "statusMessage": "Accepted, pending process."
        }
    ]
}

Sample 2: B2C senario where the value of quotaAccmulationMethod is RECEIVING_ACCOUNT

Request

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "RECEIVING_ACCOUNT",
    "quotaAccumulationId": "7276*****",
    "platform": "AE",
    "tradeOrder": [
        {
            "referenceOrderNo": "2810241509776641178*****",
            "orderTime": "2023-01-10T21:18:24Z",
            "payTime": "2023-01-10T21:28:24Z",
            "orderType": "LOAN",
            "tradeType": "GOODS",
            "tradeAmount": {
                "value": 500,
                "currency": "USD"
            },
            "transAmount": {
                "value": 500,
                "currency": "USD"
            },
            "merchant": {
                "store": {
                    "storeShopUrl": "//www.aliexpress.com/store/56*****"
                }
            },
            "buyer": {
                "buyerName": {
                    "fullName": "MICROSOFT"
                }
            },
            "goods": [
                {
                    "goodsName": "*****",
                    "goodsCategory": "Jewelry & Access*****",
                    "goodsQuantity": "1"
                }
            ],
            "shipping": {
                "wayBillInfo": [
                    {
                        "shippingOrderReferenceNo": "RM450941*****",
                        "shippingAddress": {
                            "address1": "Калининград г, Калининградская обл, Менделее*****",
                            "city": "Калининг*****",
                            "region": "RU"
                        }
                    }
                ]
            }
        }
    ]
}

Response

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
    },
    "requestId": "20230222191210001100300007*****",
    "tradeOrderResults": [
        {
            "referenceOrderNo": "2810241509776641178*****",
            "orderStatus": "ACCEPT",
            "statusMessage": "Accepted, pending process."
        }
    ]
}

Sample 3: B2C scenario where the value of quotaAccmulationMethod is BENEFICIARY

Request

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "BENEFICIARY",
    "quotaAccumulationId": "7276*****",
    "platform": "MICROSOFT",
    "tradeOrder": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderTime": "2023-04-21T22:18:24Z",
            "payTime": "2023-04-21T22:18:24Z",
            "orderType": "LOAN",
            "tradeType": "SERVICE",
            "tradeAmount": {
                "value": 500,
                "currency": "USD"
            },
            "transAmount": {
                "value": 500,
                "currency": "USD"
            },
            "revenueShare": "100",
            "buyer": {
                "buyerName": {
                    "fullName": "MICROSOFT"
                }
            },
            "seller": {
                    "customerName": "David*****"
            },
            "goods": [
                {
                    "goodsName": "ARTICAL_DISPLAY",
                    "goodsQuantity": "125***"
                }
            ],
            "market": "CHN"
        }
    ]
}

Response

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "requestId": "20230222191210001100300007*****",
    "tradeOrderResults": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderStatus": "ACCEPT",
            "statusMessage": "Accepted, pending process."
        }
    ]
}

Sample 4: B2B scenario where the value of quotaAccmulationMethod is TRANSFER_ID

Request

copy
{
    "requestId": "16782687*****",
    "sceneCode": "CREATE_B2B_ORDERS",
    "quotaAccumulationMethod": "TRANSFER_ID",
    "quotaAccumulationId": "20230308191210001100300007*****",
    "tradeOrders": [
        {
            "referenceOrderNo": "trade_order16782687*****",
            "tradeType": "GOODS",
            "orderTime": "2023-01-10T21:18:24Z",
            "isUsedForExchange": "Y",
            "tradeAmount": {
                "currency": "USD",
                "value": "2999"
            },
            "transAmount": {
                "currency": "USD",
                "value": "2999"
            },
            "bizContractInfo": {
                "buyerEnName": "阿联*****",
                "contractList": [
                    {
                        "fileKey": "sd*****",
                        "fileName": "sa*****"
                    }
                ],
                "deliverCountry": "JP",
                "tradeCountry": "JP"
            },
            "goods": [
                {
                    "goodsCnName": "微软*****",
                    "goodsName": "Microsoft Ergonomic Keyboard (LXM-0*****",
                    "goodsQuantity": "3",
                    "goodsUnit": "KG",
                    "storeUrl": "http://sd*****"
                }
            ],
            "shipping": {
                "expectedShippingDate": "16594306*****",
                "isDeclared": "N",
                "isNewBuyer": "N",
                "isShipped": "N",
                "tradeTerms": "CFR",
                "wayBillInfos": [
                    {
                        "logisticsCompany": {
                            "providerKey": "HYESL",
                            "providerValue": "阿联酋*****"
                        },
                        "shippingMethod": "RAILWAY",
                        "shippingOrderReferenceNo": "12*****",
                        "shippingProofAttachmentList": [
                            {
                                "fileKey": "sd*****",
                                "fileName": "sa*****"
                            }
                        ]
                    }
                ]
            },
            "storeWebSites": {
                "fileKey": "sd*****",
                "fileName": "sa*****"
            },
            "otherAttachmentList": [
                {
                    "fileKey": "remarkfilefi*****",
                    "fileName": "remarkfilefil*****"
                }
            ],
            "attachmentDesc": "123*****"
        }
    ]
}

Response

copy
{
  "acceptOrderId": "20230308191680008004600000*****",
  "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    }
}