​

支付中台-聚合支付项目文档

1 全局字典及其他约定

1.1 状态: status

1.2 认证/支付类型: authen_type

1.3 业务方事件回调

2 API安全约定

本期API协议头部需带上鉴权标识才可访问。具体分为： 后台管理API访问鉴权、内部服务访问鉴权。

3.1 后台管理API

3.1.1 域名

3.1.2 后台管理鉴权

使用《4.1 支付中台后台登录》返回的结果 access_token 值，HTTP 头部名称为remacToken ，发送请求时带上这个头部。

HTTP头部名称：remacToken: 值："返回的结果 access_token"

3.2 受信内部服务API

受信的下游平台使用支付中台能力调用中台接口API时需要使用。

3.2.1 域名

3.2.2 受信内部服务鉴权

请参照以下平台指引完成生成token并将随机16位AES加密密钥的密文作为头部传给中台。

HTTP头部名称：aeskey: 值："中台公钥加密的密文"

HTTP头部名称：token， 值：使用AES加密密钥明文按约定字段生成的JSON字符串密文

https://confluence.mideazy.com/pages/viewpage.action?pageId=391872567

3.3 支付相关API及鉴权

3.3.1 支付相关API域名

3.3.2 支付相关接口鉴权

受信内部服务方（业务方）调用《4.4.1.1 微信认证获取token》或 《1.4.2.1 支付宝认证获取token》获取

的 token 值携带至HTTP头部。

HTTP头部名称：Authorization : 值："调用认证获取的token"

token 中将加密存储支付相关的重要信息，由网关统一转发至聚合支付微服务，不再由业务方传参，减少了敏感信息泄露的风险，接口参数也更加简洁。

4 API

4.1 支付中台后台登录

注：登录接口使用的是统一登录的域名。 支付中台后台帐号登录后进行的操作。

参见：

http://arch.smartmideazy.com/docs/account/account-doc.html

统一登录域名

登录返回：

{"code":"200","data":{"tokenInfo":{"name":"功夫熊猫","orgFullName":null,"id":"28449","orgId":null,"org_code":null,"user_name":"supperadm","position":"未知","mobile":"13923403549","nick_name":null,"is_supper":2,"status":1,"bizOrgId":null,"bizOrgCode":null,"bizOrgFullName":null,"ico":"https://iot-xlink-xfile.oss-cn-hangzhou.aliyuncs.com/community/2022-09-01/219061661994225824.png","credentials":"U2FsdGVkX1%2Fr%2FOXMu0sZ6LW7GTMSDkrh7VOOuMU%2FyqiEa77Xh5Du1cGsm35VE2wk","roles":null,"orgRoles":null,"tenantId":null,"top_org_code":null,"top_org_id":null,"encryptKey":"oCkMsXhap7l8sex%2FlM4jtiOPQAc0cg9RE86OiMS07p8%2BE%2FVY4qG5JKXE4I0Yn2FB23HgMfIRpRzAQYh%2FUyV%2BldylfJABuedskTMAG5ainm9Ffq0JlMBi6K72%2BpY%2Bvx7%2B%2FeFjhKVMbiztZnVRxA4O9CMSFds2QbKMCopHmttWc9U%3D"},"token":{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMjg0NDkiLCJzcmMiOjEsInVzZXJfbmFtZSI6InN1cHBlcmFkbSIsInJvbGVzIjpbIlNZU19BRE1JTiJdLCJzY29wZSI6WyJhbGwiXSwibmFtZSI6IuWKn-Wkq-eGiueMqyIsImlkIjoiMjg0NDkiLCJleHAiOjE2Njc1ODEyNTcsImp0aSI6IjhkNTVjOGI5LTU0MWUtNDhkMS1hZmZiLTlmMmRmNTNjZWJhYSIsImNsaWVudF9pZCI6ImJvc3MtY2xpZW50IiwiaXNfc3VwcGVyIjoiMiJ9.UAoL0F3deAjLPekpMF56KeL7-pa1nKHZThO5oWj1Lh_6iwMV9y7OPXvwbvCE_6wpJtw7fJ19-ILaGbMyRqjH4udnt1LnIVdCioqmgnWOtvngyUNklGANZ45tuN_ALDejsmt6ayYPOmRj2Uwv468FwRhXlB2KhtEu9nKtjbNqE2k","token_type":"bearer","refresh_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMjg0NDkiLCJzcmMiOjEsInVzZXJfbmFtZSI6InN1cHBlcmFkbSIsInJvbGVzIjpbIlNZU19BRE1JTiJdLCJzY29wZSI6WyJhbGwiXSwiYXRpIjoiOGQ1NWM4YjktNTQxZS00OGQxLWFmZmItOWYyZGY1M2NlYmFhIiwibmFtZSI6IuWKn-Wkq-eGiueMqyIsImlkIjoiMjg0NDkiLCJleHAiOjE2Njc5MDUyNTcsImp0aSI6IjZkMTkzMmE3LTY2MjAtNGVlZS05ZTVhLTkzNmUyNzcyOTRlNiIsImNsaWVudF9pZCI6ImJvc3MtY2xpZW50IiwiaXNfc3VwcGVyIjoiMiJ9.iYYygwm2TFXtbVAX1FPTyGWb7kmuajHCizoV3KtKmTPC2fcxKDnizuk6_cGCQzX8u1kATm7ft2uHeyDIRMpzyZ8RTnJV7uXxV3jSAXEq-KzRtnXFsrYU9TPUvRjWw3VFK0Sy3KNWQ1X9Sb9NcdnAX5YkSpJOSprqBs35gSQ57fY","scope":"all","jti":"8d55c8b9-541e-48d1-affb-9f2df53cebaa","expires_in":35999,"roles":["SYS_ADMIN"],"top_org_id":null,"top_org_code":null,"isSys":null}},"message":"success"}

4.2 收银台模板

4.2.1 收银台模板新增

注：模板可以有多个，以便业务绑定。

URL: /v1/ploypay/admin/pay/template/set

method :PUT

HTTP头部：见《3.1.2 后台管理鉴权》

Body: 属性

Body:

{
 pay_methods:[
{key:"wechat", value:"微信"}, {key:"alipay", value:"支付宝"},
{key:"unionpay", value:"银联"}],
pay_methods_set: ["wechat", "alipay"],
status: 1 
template_type: 'mobile',
url: 'https://abc.com/index.html#',
effect_time: 15 ,
id: 1234
}

4.2.2 商户APP应用登记

URL: /v1/ploypay/admin/app/manage

method: PUT

HTTP头部：见《3.1.2 后台管理鉴权》

在开通微信公众号/小程序等相关功能时已经绑定了 Adapay 的 App_ID 与微信的 AppID 之间的映射关系，故交易时候请传入 Adapay 的 App_ID。

参见： https://docs.adapay.tech/help/console.html#appid-adapay-app-id

4.3 中台分帐接口文档

4.3.1 企业对象

4.3.1.1 创建/更新企业用户

暂支持创建企业用户对象。

URL: /v1/ploypay/admin/member/create

method: PUT

HTTP头部：见《3.2.2 受信内部服务鉴权》

BODY:

返回：

4.3.1.2 查询企业用户

URL: /v1/ploypay/admin/member/query

method: POST

HTTP头部：见《3.2.2 受信内部服务鉴权》

BODY:

返回：

{"code": "200",
"message":"success",
"data": 
{
   "id":XXX, 
  "address": "湖南省滨州市",
  "app_id": "app_XXXXXXXX",
  "area_code": "4201",
  "business_scope": "",
  "email": "",
  "legal_cert_id": "#011pvYcG/6l6ofY38Ql6P31eUb/xoAqNLSL",
  "legal_cert_id_expires": "",
  "legal_mp": "#0 11HGjFbJFO8mBejceLLqFypw==",
  "legal_person": "xxxx",
  "member_id": "member_id_test",
  "name": "测试企业用户信息 4",
  "prov_code": "0042",
  "social_credit_code": "91410300X148288455",
  "social_credit_code_expires": "",
  "telphone": "",
  "zip_code": "",
  "status": "succeeded",
  "prod_mode": "true"
}
}

4.3.2 结算帐户

4.3.2.1 创建结算帐户

URL: /v1/ploypay/admin/settleaccount/create

method: POST

HTTP头部：见 《3.2.2 受信内部服务鉴权》

BODY:

account_info 对象属性如下：

成功响应格式：

{"code": "200",
"message":"success",
"data": 
{  
  "account_info": {
      "area_code": "1401",
      "bank_acct_type": "2",
      "bank_code": "0105999",
      "bank_name": "",
      "card_id": "622700****0576",
      "card_name": "xxx",
      "cert_id": "1401****0631",
      "cert_type": "00",
      "prov_code": "0014",
      "tel_no": "137****xxxx"
  },
  "app_id": "app_XXXXXXXX",
  "channel": "bank_account",
  "create_time": "1568963254",
  "settle_account_id": "0006440476699456",
  "type": "",
  "status": "succeeded",
  "prod_mode": "true",
  "id":XX 
}

}

其中： settle_account_id 是聚合支付渠道商平台生成一个唯一的 id。

status见全局字典《A001 状态 status》

4.3.2.2 修改结算帐户配置

注： 本接口不能更改结算卡，如需更改结算账户的结算卡，请先删除结算账户，再重新创建结算账户。

URL: /v1/ploypay/admin/settleaccount/config/set

method: PUT

HTTP头部：见 《3.2.2 受信内部服务鉴权》

请求BODY:

account_info字段说明：

成功响应格式：

{"code": "200",
"message":"success",
"data": 
{  
  "account_info": {
      "area_code": "1401",
      "bank_acct_type": "2",
      "bank_code": "0105999",
      "bank_name": "",
      "card_id": "622700****0576",
      "card_name": "xxx",
      "cert_id": "1401****0631",
      "cert_type": "00",
      "prov_code": "0014",
      "tel_no": "137****xxxx"
  },
  "app_id": "app_XXXXXXXX",
  "channel": "bank_account",
  "create_time": "1568963254",
  "settle_account_id": "0006440476699456",
  "type": "",
  "status": "succeeded",
  "prod_mode": "true",
  "id":XX,
  "min_amt":  "20.00",
  "remained_amt":  "50.00",
  "channel_remark":  "摘要测试"
}

}

4.3.2.3 查询结算帐户

注： 本接口不能更改结算卡，如需更改结算账户的结算卡，请先删除结算账户，再重新创建结算账户。

URL: /v1/ploypay/admin/settleaccount/query

method: POST

HTTP头部：见 《3.2.2 受信内部服务鉴权》

请求BODY:

成功响应格式：

{"code": "200",
"message":"success",
"data": 
{  
  "account_info": {
      "area_code": "1401",
      "bank_acct_type": "2",
      "bank_code": "0105999",
      "bank_name": "",
      "card_id": "622700****0576",
      "card_name": "xxx",
      "cert_id": "1401****0631",
      "cert_type": "00",
      "prov_code": "0014",
      "tel_no": "137****xxxx"
  },
  "app_id": "app_XXXXXXXX",
  "channel": "bank_account",
  "create_time": "1568963254",
  "settle_account_id": "0006440476699456",
  "type": "",
  "status": "succeeded",
  "prod_mode": "true",
  "id":XX,
  "min_amt":  "20.00",
  "remained_amt":  "50.00",
  "channel_remark":  "摘要测试"
}

}

4.3.2.4 删除结算帐户

注： 本接口不能更改结算卡，如需更改结算账户的结算卡，请先删除结算账户，再重新创建结算账户。

URL: /v1/ploypay/admin/settleaccount/delete/{app_id}/{member_id}/{settle_account_id}

method: DELETE

HTTP头部：见《3.2.2 受信内部服务鉴权》

请求路径参数：

成功响应格式：

{"code": "200",
"message":"success",
"data": 
{  
  "account_info": {
      "area_code": "1401",
      "bank_acct_type": "2",
      "bank_code": "0105999",
      "bank_name": "",
      "card_id": "622700****0576",
      "card_name": "xxx",
      "cert_id": "1401****0631",
      "cert_type": "00",
      "prov_code": "0014",
      "tel_no": "137****xxxx"
  },
  "app_id": "app_XXXXXXXX",
  "channel": "bank_account",
  "create_time": "1568963254",
  "settle_account_id": "0006440476699456",
  "type": "",
  "status": "succeeded",
  "prod_mode": "true",
  "id":XX,
  "min_amt":  "20.00",
  "remained_amt":  "50.00",
  "channel_remark":  "摘要测试"
}

}

4.3.2.5 查询结算帐户

注： 本接口不能更改结算卡，如需更改结算账户的结算卡，请先删除结算账户，再重新创建结算账户。

URL: /v1/ploypay/admin/settleaccount/history

method: POST

HTTP头部：见《3.2.2 受信内部服务鉴权》

请求BODY :

成功响应

{"code": "200",
"message":"success",
"data": 
{
    "prod_mode": "true",
    "settle_details": [
        {
            "settle_type": "T1",
            "settle_stat": "successed",
            "card_no": "130234****8399",
            "settle_amt": "6.98",
            "settle_fee_amt": "0.00",
            "settle_date": "20191014",
            "card_name": "adapay测试商户"
        },
        {
            "settle_type": "T1",
            "settle_stat": "successed",
            "card_no": "130234****8399",
            "settle_amt": "5.00",
            "settle_fee_amt": "0.00",
            "settle_date": "20191012",
            "card_name": "adapay测试商户"
        }
    ],
    "object": "list",
    "status": "succeeded"

}

}

status 见数据字典 《A001 状态 status》

settle_details字段说明：

4.3.2.6 查询交易流水

URL: /v1/ploypay/admin/trade/history

method: POST

HTTP头部：见《3.2.2 受信内部服务鉴权》

请求BODY :

4.4 认证授权

由业务端调用中台的接口来实现认证授权。一方面返回微信和支付宝的用户ID，另一方面由中台加密生成token，后续作为请求中台的凭证。

4.4.1 微信认证授权

4.4.1.1 微信认证获取token

同时支持微信APP、小程序、公众号的授权。

协议： https

URL: /wx/wechat/token/grant

method: POST

HTTP头部：见《3.2.2 受信内部服务鉴权》

body:

返回结果:

{
   "code": "200",
   "message": "成功", 
   "data":
     {"openid":"o6Cx46ISmbJ1oWL8-_KS7YWev7RQ","nickname":"鹏哥","headimgurl":"https:\/\/thirdwx.qlogo.cn\/mmopen\/vi_32\/HkUibecHmjWIpYtGZAq0M3TbUFXibLkVyH6AGxibQT14kE6IIM4wH0ic9w54zwz6A6DWoM21YYpYheDqwlkbwZyKwA\/132","privilege":[],"unionid":"oEIwe55PabJu_9X0ThpIiKVHi5kI", "token":"eyJhbGciOiJIUzI1NiJ9.eyJrZXlfbWVtYmVyX2xvZ2luIjoie1widW5pb25pZFwiOlwib0VJd2U1NVBhYkp1XzlYMFRocElpS1ZIaTVrSVwiLFwib3BlbmlkXCI6XCJvNkN4NDZJU21iSjFvV0w4LV9LUzdZV2V2N1JRXCIsXCJuaWNrbmFtZVwiOlwi6bmP5ZOlXCIsXCJjaXR5XCI6XCJcIixcInByb3ZpbmNlXCI6XCJcIixcImNvdW50cnlcIjpcIlwiLFwiaGVhZGltZ3VybFwiOlwiaHR0cHM6Ly90aGlyZHd4LnFsb2dvLmNuL21tb3Blbi92aV8zMi9Ia1VpYmVjSG1qV0lwWXRHWkFxME0zVGJVRlhpYkxrVnlINkFHeGliUVQxNGtFNklJTTR3SDBpYzl3NTR6d3o2QTZEV29NMjFZWXBZaGVEcXdsa2J3WnlLd0EvMTMyXCIsXCJzZXhcIjowLFwibGFuZ3VhZ2VcIjpcIlwiLFwicHJpdmlsZWdlXCI6W10sXCJhdXRoZW5fdHlwZVwiOlwid2VjaGF0XCIsXCJidXNpbmVzc190eXBlXCI6XCJwYXJrcGF5XCIsXCJzcGFjZV9pZFwiOjEwMjAsXCJzcGFjZV9uYW1lXCI6XCLnvo7nmoTniankuJrmmbrmhaflgZzovablnLpcIixcImFwcElkXCI6XCJ3eGE5YzExOTMwZGUxY2U3MDZcIixcImFwcFNlY3JldFwiOlwiNTRhMzYxYjUyNjY0MjcyZDIzMmE3NTgyZGE3NDMyODRcIixcInNob3BpZFwiOjF9IiwiZXhwIjoxNjM4MjQzOTMyLCJpYXQiOjE2MzgyMzY3MzIsImp0aSI6IjA2MGUyZGVlLTdhOTQtNGYyNi05ZjA3LWM1MmMzZGViYmVmZiJ9.4J_5ES4sI6v5rf1fxlrPo_6X1c8x6d5ac58fGJcjdQ8
"     
   }

}

重要返回字段:

4.4.2 支付宝认证授权

支付宝API： https://opendocs.alipay.com/open/284/106000?ref=api

注：支付宝APP需要使用APP支付宝登录。见《APP支付宝登录产品介绍》

见：https://opendocs.alipay.com/open/218/105329/

4.4.2.1 业务方换取授权链接

4.4.2.1 支付宝认证获取token

同时支持支付宝生活号证获取token

中台网关响应

/wx/alipay/callback?app_id=2019012263118366&source=alipay_app_auth&state=SOCIAL$2059$PENDING&app_auth_code=72eb27532a0d4fcf8e6ec7e736990X64

授权成功后，获取access_token ，由 access_toke换取用户支付宝用户 user_id 即buyer_id

协议： https

URL: /wx/alipay/token/grant

method: POST

HTTP头部：见《3.2.2 受信内部服务鉴权》

body:

返回结果:

{
   "code": "200",
   "message": "成功", 
   "data":
     {"user_id":"o6Cx46ISmbJ1oWL8-_KS7YWev7RQ","token":"eyJhbGciOiJIUzI1NiJ9.eyJrZXlfbWVtYmVyX2xvZ2luIjoie1widW5pb25pZFwiOlwib0VJd2U1NVBhYkp1XzlYMFRocElpS1ZIaTVrSVwiLFwib3BlbmlkXCI6XCJvNkN4NDZJU21iSjFvV0w4LV9LUzdZV2V2N1JRXCIsXCJuaWNrbmFtZVwiOlwi6bmP5ZOlXCIsXCJjaXR5XCI6XCJcIixcInByb3ZpbmNlXCI6XCJcIixcImNvdW50cnlcIjpcIlwiLFwiaGVhZGltZ3VybFwiOlwiaHR0cHM6Ly90aGlyZHd4LnFsb2dvLmNuL21tb3Blbi92aV8zMi9Ia1VpYmVjSG1qV0lwWXRHWkFxME0zVGJVRlhpYkxrVnlINkFHeGliUVQxNGtFNklJTTR3SDBpYzl3NTR6d3o2QTZEV29NMjFZWXBZaGVEcXdsa2J3WnlLd0EvMTMyXCIsXCJzZXhcIjowLFwibGFuZ3VhZ2VcIjpcIlwiLFwicHJpdmlsZWdlXCI6W10sXCJhdXRoZW5fdHlwZVwiOlwid2VjaGF0XCIsXCJidXNpbmVzc190eXBlXCI6XCJwYXJrcGF5XCIsXCJzcGFjZV9pZFwiOjEwMjAsXCJzcGFjZV9uYW1lXCI6XCLnvo7nmoTniankuJrmmbrmhaflgZzovablnLpcIixcImFwcElkXCI6XCJ3eGE5YzExOTMwZGUxY2U3MDZcIixcImFwcFNlY3JldFwiOlwiNTRhMzYxYjUyNjY0MjcyZDIzMmE3NTgyZGE3NDMyODRcIixcInNob3BpZFwiOjF9IiwiZXhwIjoxNjM4MjQzOTMyLCJpYXQiOjE2MzgyMzY3MzIsImp0aSI6IjA2MGUyZGVlLTdhOTQtNGYyNi05ZjA3LWM1MmMzZGViYmVmZiJ9.4J_5ES4sI6v5rf1fxlrPo_6X1c8x6d5ac58fGJcjdQ8
"     
   }

}

重要返回字段:

4.5 支付

本期API仅实现汇付分帐支付。

4.5.1 统一下单

说明：本接口微信、支付宝统一下单共用接口。平台启用间连支付通道，调用的第三方聚合支付通道，由第三方支付渠道调用微信或支付宝的接口完成下单，按执行了分帐逻辑；平台启用的直连支付通道，是直接调用微信/支付宝的官方下单接口。

URL: /wx/poly/pay/unifyOrder

Method: PUT

HTTP头部：见《3.3 支付相关API及鉴权》

BODY:

重要返回字段:

div_members 对象示例：

[{
   member_id:"XX"
   amount: 120
   fee_flag:"N"

},...]

调用第三方渠道分帐支付接口时，分账对象信息 div_members 由中台来完成。不需要业务方传参。

分账对象信息div_members 由支付中台来计算。

数据结构如下：

返回数据约定：

{
  "code":"200",
  "message":"success",
  "data": {

       "transaction_id": "XXXX",
       "order_no":"XXX",
       "status": "XXX",
        "payinfo":{....}
        ...
  }



}

返回字段说明：

transaction_id: 中台交易ID

status ：支付状态， 见《1.1 状态: status》

order_no： 业务订单号

payinfo: JSONObject 微信或支付宝的预支付参数。

其中，微信的payinfo 返回字段如下：

4.5.2 查询支付对象

URL: /wx/poly/pay/query

Method: PUT

HTTP头部：见《3.3 支付相关API及鉴权》

BODY:

重要返回字段:

4.5.2 退款

URL: /wx/poly/pay/refund

Method: PUT

HTTP头部：见《3.3 支付相关API及鉴权》

BODY:

5 知识储备及参考

5.1 小程序授权

先授权登录 wx.login

wx.login({   success: res => {
             var code = res.code;
             console.log('-->授权code:'+code+');

        }

再由code 获取小程序openid

https://api.weixin.qq.com/sns/component/jscode2session?appid="+appid+"&js_code="+code+"&grant_type=authorization_code

返回：

{"session_key":"i0AYAiSWiE\/CFuo3Lh0LGg==","openid":"oVdDt5YHVN-SIBTaVFxInPc4IzuI"}

6 参考资料

汇付天下API对接：

https://docs.adapay.tech/api/index.html

商户接入指引： https://docs.adapay.tech/help/in-guidelines.html

分帐接口：

https://docs.adapay.tech/api/trade.html#payment

实时分帐业务功能：

https://docs.adapay.tech/api/busiprocess.html#id2

支付方式：

https://docs.adapay.tech/api/paytype_introduce.html#

支付流程：

https://docs.adapay.tech/api/process.html

创建分帐对象

https://docs.adapay.tech/api/busiprocess.html#id2

https://docs.adapay.tech/api/busiprocess.html#id3

结算查询：

https://docs.adapay.tech/api/trade.html#settle-detail-query

原型： https://modao.cc/app/fQuUG9vyriwuyg8BXBe4C8 #支付中台-支付中台

社区支付：

http://arch.smartmideazy.com/apidoc/main-entry/any-pay.html