submitTradeOrder

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

需要签名验签

集成商可以调用此接口提交交易订单。在提交交易订单的同时,集成商还需调用 submitAttachment 接口提交相关附件。关于提交附件的更多信息,参见 submitAttachment

此接口适用于以下两种业务场景:

  • B2C 场景
  • B2B 场景

接口结构

万里汇接口的报文结构包括:请求头、请求体、响应头和响应体。该章节主要介绍请求体和响应体的结构。关于请求头和响应头的更多信息,参见:

请求参数

字段名

数据类型

是否必填

描述

requestId

字符串

针对单次交易订单上传请求,由集成商指定的唯一请求号。

更多信息:

  • 此字段为业务幂等字段,可用于实现幂等检查。
  • 字段最大长度:64

sceneCode

字符串

业务场景代码。可取值如下:

  • CREATE_B2B_ORDERS:创建并关联 B2B 订单信息。
  • PAY_INTO_CHINA :适用于结汇场景。无须订单关联。

quotaAccumulationMethod

字符串

申报额度的累计方式。

可取值如下:

  • USER_ID :根据申报主体UID(即已入驻万里汇的用户ID)累积申报额度。
  • BATCH_NO :根据交易批次号累计申报额度。
  • RECEIVING_ACCOUNT :根据收款账号(RA)累计申报额度。
  • VIRTUAL_ACCOUNT:根据虚拟账号(VA)累计申报额度。
  • BENEFICIARY:根据收款人(即未入驻万里汇的外部平台用户)累计申报额度。
  • TRANSFER_ID:根据代发转账单号累计申报额度。
  • COLLECTION_ID:根据来账收款单号累计申报额度。

quotaAccumulationId

字符串

申报额度的累计标识。此字段的赋值规则如下:

  • quotaAccumulationMethod = USER_ID 时,传入交易卖家的用户ID
  • quotaAccumulationMethod = RECEIVING_ACCOUNT 时,传入交易卖家的收款账户(RA)
  • quotaAccumulationMethod = VIRTUAL_ACCOUNT 时,传入交易卖家的虚拟账户(VA)
  • quotaAccumulationMethod = BENEFICIARY 时,传入外部平台的用户ID
  • quotaAccumulationMethod = BATCH_NO 时,传入平台侧订单批次号
  • quotaAccumulationMethod = TRANSFER_ID 时,传入代发转账单号
  • quotaAccumulationMethod = COLLECTION_ID 时,传入来账收款单号

tradeOrders

数组<TradeOrder 对象>

交易订单列表。此字段的赋值条件如下:

  • sceneCode = CREATE_B2B_ORDERS 时,单次请求最多可上传 10 笔订单。
  • sceneCode = PAY_INTO_CHINA 时,单次请求最多支持上传 100 笔订单。

platform

SET LABEL

字符串

有使用条件

交易发生平台,用于标识外部来源。当 sceneCode = PAY_INTO_CHINA 时,此字段为必填。

notifyUrl

字符串

交易订单提交结果的异步通知地址。

更多信息:

  • 字段最大长度:256

extendInfo

SET LABEL

字符串

额外信息。

更多信息:

  • 字段最大长度:2048 字符

响应参数

字段名

数据类型

是否必填

描述

result

Result 对象

API 调用结果,即交易订单上传的请求结果。

requestId

字符串

针对单次交易订单上传请求,由集成商指定的唯一请求号。

更多信息:

  • 字段最大长度:64

acceptOrderId

字符串

有使用条件

针对单次交易订单提交请求,由万里汇指定的受理单号。当 sceneCode = CREATE_B2B_ORDERS 时,此字段为必填。

更多信息:

  • 字段最大长度:128

tradeOrderResultSET LABEL

数组 <TradeOrderResult> 对象

有使用条件

所受理的交易订单信息,包括交易单号、订单状态等。当 sceneCode = PAY_INTO_CHINA 时,此字段为必填。

响应处理

集成商调用接口后,万里汇通过 result.resultStatus 字段返回集成商 API 调用结果。此字段的取值范围如下:

result.resultStatus

描述

S

API请求成功。

F

API请求失败。具体失败原因,参见结果码(即 result.resultCoderesult.resultMessage)。

U

API响应结果为U(未知)时,集成商需重试API请求。

重试策略:

  • 重试次数上限:7次
  • 重试时间间隔:5分钟、10分钟、20分钟、40分钟、80分钟、160分钟、320分钟

如果问题依旧,请联系万里汇技术支持。

结果码

result.resultCode

resultCode

resultStatus

resultMessage

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.

参数异常

修改订单信息、更换requestId,发起重试

INVALID_SIGNATURE

F

The signature is invalid.

签名校验失败

确认请求正确加签,更换requestId,发起重试

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

幂等请求

幂等请求,无需重试

UNKNOWN_EXCEPTION

U

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

未知错误

无需更换requestId,发起重试

FUND_ORDER_NOT_EXIST

F

The fund order does not exit.

资金单不存在

联系万里汇技术支持以解决此问题

ACCESS_DENIED

F

Access is denied for submitting trade orders.

没有操作权限

联系万里汇技术支持以解决此问题

ORDER_COUNT_EXCEED_LIMIT

F

The number of associated trade orders exceeds limit.

订单关联条数超过上限

修改订单同步条数,更换订单reqeustId,发起重试

WRONG_TRADE_TYPE

F

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

订单贸易类型不支持,或

参数贸易类型不一致

联系万里汇技术支持以解决此问题

REQUEST_PARAM_AMOUNT_ERROR

F

Invalid amount parameter exists.

参数金额异常

修改订单或关联信息,更换订单 reqeustId,发起重试。

TRADE_ORDER_AUTH_STATUS_ILLEGAL

F

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

订单已经存在,且审核拒绝或者审核需补件

联系万里汇技术支持以解决此问题

RELATE_AMOUNT_ERROR

F

The intended association amount is incorrect.

关联金额异常

修改订单关联金额,更换订单reqeustId,发起重试。

注:不可修改已上传成功的订单金额

ENTITY_REGISTRATION_REQUIRED

F

Entity registration is required for uploading customs declaration.

需要同步报关单,没有完成关联主体登记

联系万里汇技术支持以解决此问题

INCONSISTENT_TRADE_TYPE

F

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

订单再次部分关联时和历史关联订单贸易类型不一致

联系万里汇技术支持以解决此问题

UN_SUPPORT_BUSINESS

F

Unsupported business.

包含无效参数

包含无效参数,使用正确参数重试

CONTRACT_CHECK_FAIL

F

The contract check has failed.

合约状态异常

检查合约状态后重试

REGULATED_COUNTRY_NOT_SUPPORTED

F

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

为了您的资金安全,我们暂不支持买家国家(tradeCountry) 或收货国家(deliverCountry)为受管制国家的订单。

查看受管制国家的完整名单,点击参数介绍。详情请咨询万里汇技术支持。

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

存在重复且不一致请求。

确保请求中相同字段赋值一致后重试

FUND_ORDER_RELATED_MANUALLY

F

Fund order has already been manually related to the trade order. 

资金单已被手动关联至交易单。

检查已关联的资金单是否正确,若无误则无需重复关联资金单。

代码示例

示例一:B2C 场景

请求体

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "USER_ID",
    "quotaAccumulationId": "21201200791*****",
    "platform": "AE",
    "tradeOrders": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderTime": "2023-01-10T21:18:24Z",
            "paymentTime": "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": {
                "wayBillInfos": [
                    {
                        "shippingOrderReferenceNo": "RM450941*****",
                        "shippingAddress": {
                            "address1": "Калининград г, Калининградская обл, Менделее*****",
                            "city": "Калининг*****",
                            "region": "RU"
                        }
                    }
                ]
            }
        }
    ]
}

响应体

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

示例二:B2C 场景

请求体

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "RECEIVING_ACCOUNT",
    "quotaAccumulationId": "7276*****",
    "platform": "AE",
    "tradeOrders": [
        {
            "referenceOrderNo": "2810241509776641178*****",
            "orderTime": "2023-01-10T21:18:24Z",
            "paymentTime": "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": {
                "wayBillInfos": [
                    {
                        "shippingOrderReferenceNo": "RM450941*****",
                        "shippingAddress": {
                            "address1": "Калининград г, Калининградская обл, Менделее*****",
                            "city": "Калининг*****",
                            "region": "RU"
                        }
                    }
                ]
            }
        }
    ]
}

响应体

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

示例三:B2C 场景

请求体

copy
{
    "requestId": "20230222191210001100300007*****",
    "sceneCode": "PAY_INTO_CHINA",
    "quotaAccumulationMethod": "BENEFICIARY",
    "quotaAccumulationId": "7276*****",
    "platform": "MICROSOFT",
    "tradeOrders": [
        {
            "referenceOrderNo": "50957342066*****",
            "orderTime": "2023-04-21T22:18:24Z",
            "paymentTime": "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"
        }
    ]
}

响应体

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

示例四:B2B 场景

请求体

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*****"
        }
    ]
}

响应体

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

@2024 WorldFirst