133 lines
12 KiB
Markdown
133 lines
12 KiB
Markdown
接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。
|
||
|
||
接口英文名：SimplePay
|
||
|
||
<font style="color:rgb(34, 34, 34);">本接口用于发起简易支付</font>。消费者可通过微信或者支付宝打开返回的支付链接进行支付。
|
||
|
||
1. <font style="color:#E8323C;">当前简易支付返回的支付链接为聚合链接，支持使用微信APP和支付宝APP打开进行支付。但是同一个简易支付链接，如果消费者已经使用微信APP打开过后，不可再使用支付宝APP打开再进行支付。</font>
|
||
2. 消费者用微信APP或者支付宝APP打开交易中心提供的简易支付链接后，需要1分钟内完成支付，如超时未支付，需要重新下单获取新的简易支付链接。
|
||
3. 简易支付的原理是：消费者打开交易中心提供的简易支付链接后，由交易中心获取消费者在交易中心的APPID下的openid,并通过JSAPI的支付方式进行下单获取支付参数，最后唤起用户的付款页面。本质上该支付方式为JSAPI支付。
|
||
4. <font style="color:#E8323C;">交易中心会根据业务的发展，视情况增加请求参数和返回参数，请服务商/商户侧提前做好兼容。</font>
|
||
|
||
## 1、调用方式
|
||
### HTTPS调用
|
||
`POST <font style="color:rgb(52,64,84);">/api/app/payOreder/simplePay</font>`
|
||
|
||
## 2、请求参数
|
||
### <font style="color:rgb(34, 34, 34);">请求体 </font>`<font style="color:rgb(34, 34, 34);">Request Payload</font>`
|
||
| 参数名 | 类型 | 必填 | 字段长度 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| service | string | 是 | - | 接口名称。<font style="color:rgb(232,50,60);">此处固定值为：get_tdcode</font> |
|
||
| t0 | string | 否 | 1 | D0交易标志，默认为0<br/>0：D1交易 <br/>1：D0交易 |
|
||
| jspay_flag | string | 是 | 1 | 支付方式。<br/><font style="color:rgb(232,50,60);">本处固定填写：2</font> |
|
||
| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：<br/>MD5：MD5签名算法<br/>SM3：国密SM3签名算法 不传默认使用MD5算法 |
|
||
| merchant_id | string | 是 | 10 | 财务交易中心商户号 |
|
||
| third_order_id | string | 是 | 64 | 商户订单号。<br/>由商户或者服务商自行定义，可以包含字母。需确保同一个商户下唯一 |
|
||
| amount | string | 是 | 10 | 订单金额。<br/>单位为分，整数 |
|
||
| nonce_str | string | 是 | 32 | 随机字符串 |
|
||
| sign | string | 是 | 32 | 签名 |
|
||
| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 |
|
||
| jump_url | string | 否 | - | 支付跳转地址。<br/><font style="color:rgb(232,50,60);">当前跳转效果已不生效，服务商/商户可随意传一个地址, 或者不传该参数。</font> |
|
||
| user_name | string | 否 | - | 收银员名称 |
|
||
| notify_url | string | 否 | 128 | 交易通知地址。<br/>接收财务交易中心通知的URL，需做UrlEncode 处理，需要绝对路径，确保顺成能正确访问，若不需要回调请忽略 |
|
||
| client_ip | string | 否 | 16 | 用户IP地址。<br/>商户发起交易的IP地址 |
|
||
| body | string | 否 | 256 | 商品描述。不能包含回车、换行等特殊字符。<br/><font style="color:rgb(245,34,45);">该信息会展示在微信付款页面的“商品”中</font> |
|
||
| shop_no | string | 否 | 16 | 商户门店编号。<br/>只能是汉字、英文字母、数字 |
|
||
| attach | string | 否 | 96 | 附加数据。支付成功原样返回。<br/>注意：只能是汉字、英文字母、数字 |
|
||
| limit_pay | string | 否 | 1 | 是否禁用信用卡，枚举如下：<br/>1：禁止使用信用卡；<br/>0或者不填：不限制 |
|
||
| goods_tag | string | 否 | 32 | 订单优惠标记，，代金券或立减优惠功能。<br/>该参数财务交易中心透传给微信，当前仅对微信交易生效 |
|
||
| goods_detail | string | 否 | 8000 | 单品优惠商品详情。<br/>该字段为JSON格式的字符串<br/>1. 微信交易时，该参数透传给微信，对应微信的detail参数，主要用于微信的单品营销。<br/>参数具体内容详见下方 |
|
||
| scene_info | string | 否 | - | 场景信息。<br/><font style="color:rgb(0,0,0);">该字段用于上报场景信息，</font><font style="color:rgb(245,34,45);">仅针对微信交易有效，透传至微信。</font><font style="color:rgb(0,0,0);">目前支持上报实际门店信息。</font><br/><font style="color:rgb(245,34,45);">该字段</font><font style="color:rgb(245,34,45);">为</font><font style="color:rgb(245,34,45);">JSON</font><font style="color:rgb(245,34,45);">格式的字符串。</font><br/><font style="color:rgb(0,0,0);">参数具体内容：{"store_info":{"id": "门店 ID","name ": "名称","area_code": "编码","address": "地址"}}</font> |
|
||
| need_receipt | boolean | 否 | - | 电子发票功能。<br/>仅针对微信交易有效，需要和微信公众平台的发票功能联合使用。枚举如下：<br/>1. true<br/>2. false<br/>（只能为true或false，只支持全小写字母或全大写字母） |
|
||
| gps_info | string | 否 | 512 | gps信息。<br/>校验GPS信息格式， 如：-128.12,23.1 -- 1. xxx,xxx -- 2. 经度xxx为[-180，180]之间的浮点数，维度 |
|
||
| bs_info | string | 否 | 512 | 基站信息。<br/>校验基站信息格式, <br/>格式说明： -- 1. 格式为：xxx,xxx,xxx,xxx 如：460,1,12,23454 -- 2. xxx均为整数，长度不超过11位<br/>基站信息，从左至右依次对应以下几个字段： mcc: 移动国家号码，由3位数字组成，唯一地识别移动用户所属的国家。我国为460 mnc:移动网号，由两位数字组成，用于识别移动用户所归属的移动网 lac:位置区编码,为寻呼而设置的一个区域，覆盖一片地理区域，按寻呼量划分 ci :负责收发的天线所朝向的扇区编号 |
|
||
|
||
|
||
#### `goods_detail字段说明`
|
||
微信交易时，该参数对应透传至微信的detail参数
|
||
|
||
| 参数名 | 类型 | 必填 | 字段长度 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| <font style="color:rgb(0,0,0);">cost_price</font> | int | 否 | - | <font style="color:rgb(0,0,0);">订单原价。</font><br/><font style="color:rgb(0,0,0);">1.</font><font style="color:rgb(0,0,0);">商户侧一张小票订单可能被分多次支付，订 单原价用于记录整张小票的交易金额。 </font><br/><font style="color:rgb(0,0,0);">2.</font><font style="color:rgb(0,0,0);">当订单原价与支付金额不相等，则不享受优惠。 </font><br/><font style="color:rgb(0,0,0);">3.该字段主要用于防止同一张小票分多次支 付，以享受多次优惠的情况，正常支付订单不 必上传此参数</font> |
|
||
| <font style="color:rgb(0,0,0);">receipt_id</font> | string | 否 | 32 | <font style="color:rgb(0,0,0);">商品小票 ID。商家小票 ID</font> |
|
||
| <font style="color:rgb(0,0,0);">goods_detail</font> | object | 是 | - | <font style="color:rgb(0,0,0);">单品列表</font><font style="color:rgb(0,0,0);">。</font><br/><font style="color:rgb(0,0,0);">单品信息，使用 Json 数组格式提交</font> |
|
||
| ┗<font style="color:rgb(0,0,0);">goods_id</font> | string | 是 | 32 | <font style="color:rgb(0,0,0);">商品编码。</font><br/><font style="color:rgb(0,0,0);">由半角的大小写字母、数字、中划线、下划线中的一种或几种组成</font> |
|
||
| ┗<font style="color:rgb(0,0,0);">wxpay_goods _id</font> | string | 否 | 32 | <font style="color:rgb(0,0,0);">微信侧商品编码。</font><br/><font style="color:rgb(0,0,0);">微信支付定义的统一商品编号（没有可不传）</font> |
|
||
| ┗<font style="color:rgb(0,0,0);">goods_name</font> | string | 否 | 256 | <font style="color:rgb(0,0,0);">商品名称。</font><br/><font style="color:rgb(0,0,0);">商品的实际名称</font> |
|
||
| ┗<font style="color:rgb(0,0,0);">quantity</font> | int | 是 | - | 商品数量。<br/><font style="color:rgb(0,0,0);">用户购买的数量</font> |
|
||
| ┗<font style="color:rgb(0,0,0);">price</font> | int | 是 | - | 商品单价。<font style="color:rgb(0,0,0);">单位为：分。</font><br/><font style="color:rgb(0,0,0);">如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔 100 元的订单使用了商场发的优惠券 100-50，则活动商品的单价应为原单价-50)</font> |
|
||
|
||
|
||
#### `<font style="color:rgb(0,0,0);">scene_info</font>字段说明`
|
||
| 参数名 | 类型 | 必填 | 字段长度 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| <font style="color:rgb(0,0,0);">id</font> | string | <font style="color:rgb(0,0,0);">否</font> | 32 | <font style="color:rgb(0,0,0);">门店 id。门店唯一标识</font> |
|
||
| <font style="color:rgb(0,0,0);">name</font> | string | 否 | 64 | 门店名称 |
|
||
| <font style="color:rgb(0,0,0);">area_code</font> | string | 否 | 6 | 门店行政区划码。<font style="color:rgb(0,0,0);">门店所在地行政区划码</font> |
|
||
| <font style="color:rgb(0,0,0);">address</font> | string | 否 | 128 | <font style="color:rgb(0,0,0);">门店详细地址</font> |
|
||
|
||
|
||
## 3、返回参数
|
||
### <font style="color:rgb(34, 34, 34);">返回体 </font>`<font style="color:rgb(34, 34, 34);">Response Payload</font>`
|
||
XML格式返回
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| resp_code | string | 通信状态码。<br/>200 - 成功。<br/>非200 - 失败。<br/>注：此字段是通信标识，业务状态要看result_code |
|
||
| resp_msg | string | 通信错误说明<br/>resp_code非200时返回 |
|
||
| req_serial_no | string | 本次交易的请求流水号，原样返回 |
|
||
| <font style="color:rgb(232,50,60);">以下参数在resp_code=200时返回</font> | | |
|
||
| result_code | string | 业务状态码。<br/>0 - 支付受理成功<br/>非0 - 支付受理失败 |
|
||
| error_code | string | 支付失败错误码。<br/>支付失败时返回<br/>错误码 |
|
||
| error_msg | string | 支付失败原因。<br/>支付失败时返回具体失败原因说明 |
|
||
| nonce_str | string | 随机字符串 |
|
||
| sign | string | 签名 |
|
||
| sign_type | string | 签名类型，枚举如下：<br/>MD5：MD5签名算法<br/>SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 |
|
||
| cost_time | string | 请求耗时。<br/>请求接口耗费的时间，单位毫秒 |
|
||
| merchant_id | string | 财务交易中心商户号 |
|
||
| third_order_id | string | 商户订单号。<br/>由商户/服务商侧自主生成 |
|
||
| schc_order_id | string | 财务交易中心交易订单号 |
|
||
| <font style="color:rgb(232,50,60);">以下参数在result_code=0时返回</font> | | |
|
||
| jspay_url | string | 简易支付url。<br/>重定向到该url可以完成后续支付流程。<br/>返回二维码链接有效期为10分钟。<br/><font style="color:rgb(232,50,60);">特别说明：获取该链接成功，并不一定代表该链接可进行支付。</font> |
|
||
|
||
|
||
## 4、注意事项
|
||
|
||
|
||
## 5、代码示例
|
||
请求参数：
|
||
|
||
```json
|
||
{
|
||
"service": "get_tdcode",
|
||
"jspay_flag": "2",
|
||
"sign_type": "MD5",
|
||
"merchant_id": "0000000038",
|
||
"third_order_id": "17730391726943A1F3E866823",
|
||
"amount": "1",
|
||
"nonce_str": "17730391726943A1F3E866823",
|
||
"req_serial_no": "17730391726943A1F3E866823",
|
||
"sign": "YzRkMTIzMDIzYWE0MTBkN2ExODY2ZTExNzVmNTI5MDg="
|
||
}
|
||
```
|
||
|
||
<font style="color:rgb(52, 64, 84);"></font>
|
||
|
||
<font style="color:rgb(52, 64, 84);">返回参数：</font>
|
||
|
||
```html
|
||
<schc>
|
||
<resp_code><![CDATA[200]]></resp_code>
|
||
<merchant_id><![CDATA[8153213715]]></merchant_id>
|
||
<sign><![CDATA[0DA80E12DB46CA8EFE3FFA2404CC9F26]]></sign>
|
||
<cost_time><![CDATA[6]]></cost_time>
|
||
<sign_type><![CDATA[MD5]]></sign_type>
|
||
<third_order_id><![CDATA[m20221009182459szeGpPEJ]]></third_order_id>
|
||
<nonce_str><![CDATA[ergcktjerpwjiltjohjsgypnijggqckr]]></nonce_str>
|
||
<jspay_url><![CDATA[https://qr.leshuazf.com/cgi-bin/qr/simple_pay.cgi?mid=8153213715&pu=1ux1Z1001602371522282]]></jspay_url>
|
||
<result_code><![CDATA[0]]></result_code>
|
||
<schc_order_id><![CDATA[1001602371522282]]></schc_order_id>
|
||
<req_serial_no><![CDATA[17730391726943A1F3E866823]]></req_serial_no>
|
||
</schc>
|
||
```
|