Orders API | Midasbuy OpenAPI

订单查询 API 介绍

用来查询支付订单和营销订单的最新状态。

请求处理

所有的API请求必须使用HTTPS，HTTP Method均为 POST。

接口使用JSON作为消息体的数据交换格式。请求须设置HTTP头部：

Content-Type: application/json
Accept: application/json

联调资源

现网接口地址：https://api-payments.midasbuy.com/midasbuy/
沙箱接口地址：https://sandbox-api-payments.midasbuy.com/midasbuy/

错误处理

MidasBuy使用HTTP状态码来表示请求处理的结果。

处理成功的请求，将会返回200
请求处理失败时，如缺少必要的入参，将会返回4xx范围内的错误码；
请求处理时发生了Midas侧的服务系统错误，将返回500/501/503的状态码。这种情况比较少见。

错误码和错误提示

当请求处理失败时，除了HTTP状态码表示错误之外，API将在消息体返回错误相应说明具体的错误原因。

name 唯一错误码，必选。
message 用于描述响应，非必选。
links 当发生故障时可能返回解决该问题的文档地址，非必选
details 用于给出更详尽信息，例如：重试详情、配额错误、渠道错误等；非必选。
causes 该异常的解决方案；非必选。
debug_id 当前请求的标识，用户表示Midas的一次请求。反馈问题时可带上该标识，非必选。

错误码示例：

{
    "name": "INVALID_ARGUMENT",
    "message": "invalid CreateOrderRequest.ApplicationContext: embedded message failed validation | caused by: invalid ApplicationContext.RegionCode: value does not match regex pattern \"^[A-Z]{2}$\"",
    "details": [
        {
            "@type": "type.apis.com/rpc.BadRequest.FieldViolation",
            "field": "ApplicationContext",
            "description": "embedded message failed validation",
            "value": ""
        }
    ],
    "links": [],
    "debug_id": "247df6a6ed3ab364",
    "causes": []
}

签名方法

构造签名串

签名串一共有五行，每一行为一个参数。行尾以\n（换行符，ASCII编码值为0x0A）结束，包括最后一行。如果参数本身以\n结束，也需要附加一个\n。

HTTP请求方法\n
URL\n
请求时间戳\n
请求随机串\n
请求报文主体\n

第一步，获取HTTP请求的方法（请求统一为POST）

POST

第二步，获取请求的绝对URL，并去除域名部分得到参与签名的URL。如果请求中有查询参数，URL末尾应附加有’?'和对应的查询字符串。

/midasbuy/v2/orders

第三步，获取发起请求时的系统当前时间戳，即格林威治时间1970年01月01日00时00分00秒(北京时间1970年01月01日08时00分00秒)起至现在的总秒数，作为请求时间戳。MidasPay会拒绝处理24小时之前发起的请求，请商户保持自身系统的时间准确。

$ date +%s
1725519185

第四步，生成一个请求随机串，可参见。这里，使用命令行直接生成一个。

$ hexdump -n 16 -e '4/4 "%08X" 1 "\n"' /dev/random
593BEC0C930BF1AFEB40B4A08C8FB242

第五步，获取请求中的请求报文主体（request body）。

当请求方法为POST时，请使用真实发送的JSON报文。

对于下载证书的接口来说，请求报文主体是一个空串。

第六步，按照前述规则，构造的请求签名串为：

POST
/midasbuy/v2/orders
1725519185
593BEC0C930BF1AFEB40B4A08C8FB242
${body}

${body}为请求报文主体占位符，请填入真实的报文主体

计算签名值

绝大多数编程语言提供的签名函数支持对签名数据进行签名。强烈建议商户调用该类函数，使用商户私钥对待签名串进行SHA256 with RSA签名，并对签名结果进行Base64编码得到签名值。使用命令行演示如何生成签名。

$ echo -n -e \
"POST\n/midasbuy/v2/orders\n1725519185\n593BEC0C930BF1AFEB40B4A08C8FB242\n$\{body\}\n" \
| openssl dgst -sha256 -sign apiclient_key.pem \
| openssl base64 -A
uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==

设置HTTP头

Midas要求商户请求通过HTTP Authorization头来传递签名。Authorization由认证类型和签名信息两个部分组成。

Authorization: 认证类型 签名信息

具体组成为：

认证类型，目前为TXGW-SHA256-RSA2048
签名需要包含以下内容
1. 签名信息发起请求的应用 ID： 'auth_id' ，商户注册的Midas 应用 ID（len<=64）
2. 验证标识类型：'auth_id_type'，默认为APP_ID （len<=32）
3. 商户API证书序列号：'serial_no'，用于声明所使用的证书，默认使用 1 （len<=64）
4. 请求随机串：'nonce_str'，只能使用大写英文字符、小写英文字符、数字（len=32）
5. 时间戳：'timestamp'
6. 签名值：'signature'

注：以上六项签名信息，无顺序要求。

Authorization头的示例如下：（注意，示例因为排版可能存在换行，实际数据应在一行）

Authorization: TXGW-SHA256-RSA2048 auth_id=145000000,auth_id_type=APP_ID,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,signature=uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==,timestamp=1725519185,serial_no=1

最终可以组一个包含了签名的HTTP请求了。

$ curl https://${host}/midasbuy/v2/orders -H 'Content-Type: application/json' -H 'Authorization: TXGW-SHA256-RSA2048 auth_id=145000000,auth_id_type=APP_ID,nonce_str=593BEC0C930BF1AFEB40B4A08C8FB242,signature=uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==,timestamp=1725519185,serial_no=1'

订单查询 API 介绍​

请求处理​

联调资源​

错误处理​

错误码和错误提示​

签名方法​

构造签名串​

计算签名值​

设置HTTP头​