submitTradeOrder需要签名验签

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

在以下两种业务场景中,调用此接口提交交易订单:

  • B2C
  • B2B

报文结构

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

入参

requestId String  REQUIRED

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

更多信息:

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

sceneCode String  REQUIRED

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

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

quotaAccumulationMethod String  REQUIRED

申报额度的累计方式。

可取值如下:

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

quotaAccumulationId String  REQUIRED

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

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

tradeOrders Array<TradeOrder>  REQUIRED

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

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

notifyUrl String  

URL地址,用于接收万里汇通过notifyTradeOrdernotifyAssociationResult发送的交易单关联结果。

更多信息:

  • 最大长度:256 字符

platform String B2C  CONDITIONAL

交易发生平台,用于标识外部来源。

sceneCode = PAY_INTO_CHINA 时,此字段为必传

extendInfo String B2B  

额外信息。

更多信息:

  • 最大长度:2048 字符

出参

result Result  REQUIRED

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

Show child parameters

requestId String B2C  CONDITIONAL

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

sceneCode = PAY_INTO_CHINA 时,此字段必定返回。

更多信息:

  • 此为幂等字段。集成商可使用本字段做幂等校验。
  • 最大长度:64 字符

tradeOrderResult B2C Array<TradeOrderResult>  CONDITIONAL

所受理的交易订单信息,包括交易单号、订单状态等。

sceneCode = PAY_INTO_CHINA 时,此字段必定返回。

Show child parameters

acceptOrderId String B2B  CONDITIONAL

针对单次交易订单提交请求,由万里汇指定的受理单号。

sceneCode = CREATE_B2B_ORDERS 时,此字段必定返回。

更多信息:

  • 最大长度:128 字符
API Explorer

请求

URL
Case
When sceneCode=PAY_INTO_CHINA and quotaAccumulationMethod=USER_ID
请求体

响应

Case
When sceneCode=PAY_INTO_CHINA and quotaAccumulationMethod=USER_ID
响应体

响应处理

集成商调用接口后,万里汇通过 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 结果码

结果码结果码信息行动建议
SUCCESSSSuccess
PROCESS_FAILFA general business failure occurred. Do Not retry.

需要人工介入,联系万里汇技术支持以解决此问题

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

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

INVALID_APIFThe called API is invalid or not active.

确认是否调用正确的API

INVALID_CLIENTFThe client is invalid.

Client ID不存在或无效

INVALID_SIGNATUREFThe signature is invalid.

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

REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

幂等请求,无需重试

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

无需更换requestId,发起重试

USER_NOT_EXISTFThe user does not exist.

使用正确的用户信息重试

FUND_ORDER_NOT_EXISTFThe fund order does not exit.

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

ACCESS_DENIEDFAccess is denied for submitting trade orders.

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

ORDER_COUNT_EXCEED_LIMITFThe number of associated trade orders exceeds limit.

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

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

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

REQUEST_PARAM_AMOUNT_ERRORFInvalid amount parameter exists.

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

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

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

RELATE_AMOUNT_ERRORFThe intended association amount is incorrect.

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

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

ENTITY_REGISTRATION_REQUIREDFEntity registration is required for uploading customs declaration.

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

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

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

UN_SUPPORT_BUSINESSFUnsupported business.

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

CONTRACT_CHECK_FAILFThe contract check has failed.

检查合约状态后重试

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.

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

REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.

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

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

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

@2024 WorldFirst