百福得开放平台
  • 接口文档
  • 三、积分对接
2024-11-22
目录

3.2 客户收银台示例

# 3.2 客户收银台示例

# 说明

1、相关接口由客户方提供，百福得调用

2、客户提供收银台支付页面，百福得调用下单接口返回客户的支付链接，用户点击东福的“确认支付”按钮会跳转到客户的支付页面，用户支付成功后客户方异步通知东福

3、客户收银台根据企业内部积分权益管控，也可以进行企业内部支付方式对接、微信支付宝等现金支付对接，东福关注的是支付总金额。

# 整体时序图

# 签名&加密

1、appId、appSecret由客户方提供，签名和加密共用一个秘钥，密钥长度128位(bit)=16字节(byte)，秘钥示例：fu2AJQXq5Us7o6Q7
在线密码随机生成器 (opens new window)
2、地址栏参数需要对"公共参数"进行签名，sign签名过程参考签名实现
3、原明文json字符串用AES加密后放到data中传输（加密模式：AES/ECB/PKCS5Padding）
4、服务接口规范：

POST /openApi/cash/callback/payNotify/{union}?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
   "appId": "客户分配给东福的appId",
   "data": "明文json格式的参数通过AES加密后的字符串"
}
1
2
3
4
5
6
7

5、接口传输统一使用utf-8编码，响应Content-Type为：application/json

# AES加密工具类

Java (opens new window)
C# (opens new window)
GO (opens new window)
JavaScript (opens new window)
PHP (opens new window)
Python (opens new window)

# 3.2.1 预下单接口

# 说明

1、接口由客户方提供，百福得调用，用于提交订单信息给到客户方，客户方返回收银台地址给用户，用户点击确认支付按钮跳转到收银台页面

2、相同订单号，重复请求应返回收银台地址，不应该报错

3、已支付订单打开客户收银台页面，应该返回已支付订单页面，并提示用户支付成功，不允许重复支付

# 地址

接口由客户方提供

# HTTP请求方式

Request Method: POST Content-Type: application/json

# 公共参数(URL参数，参与签名)

字段 类型 是否必填 中文意描述
appId String 是 appId，由客户方提供
timestamp String 是 毫秒级时间戳 防止重复攻击
sign String 是 签名
version String 否 业务接口版本号，如1.0.0

# body参数（参与AES加密）

参数名称 参数类型 是否必须 描述
orderSn String 是 东福订单号(幂等标识，未支付成功，重复请求应返回收银台地址)
tradeSn String 否 东福交易流水号
amount BigDecimal 是 交易金额（单位分，包含了运费+服务费）
serviceFee BigDecimal 否 服务费（单位分）
freight BigDecimal 否 运费（单位分）
account String 是 员工账号（条件必填），免密推送给东福的账号
externalNo String 否 客户系统用户唯一标识（可以通过免密或用户推送传递给东福）
costId String 否 活动场景，用于区分客户不同活动预算的标识
createOrderTime String 是 订单创建时间，yyyy-MM-dd HH:mm:ss
timeout Integer 是 订单超时时间（分钟）
payExpiredAt String 否 支付超时时间，yyyy-MM-dd HH:mm:ss
notifyUrl String 否 支付成功时，POST通知东福支付成功的地址
returnUrl String 否 支付成功时前端重定向地址，通常是订单详情页
goodsList List<Object> 否 商品信息
- goodsId String 否 商品ID
- goodsImg String 否 商品图片
- goodsName String 否 商品名称
- quantity Integer 否 商品数量
- goodsPrice BigDecimal 否 商品单价
consigneeInfo Object 否 收货信息
- consignee String 否 收件人姓名
- mobile String 否 收件人联系方式
- province String 否 省
- city String 否 市
- district String 否 区
- street String 否 街道
- address String 否 收货详细地址

# 请求示例

POST /cash/submitOrder?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
      "appId": "客户分配给东福的appId",
      "data": "密文"
}

---------------------------------注:密文对应的明文JSON示例---------------------------------
{
      "orderSn": "21250421153000105759",
      "tradeSn": "cust17452208162273009114084",
      "amount": 300,
      "serviceFee": 0.00,
      "freight": 2.00,
      "account": "zhangsan",
      "externalNo": "zhangsan",
      "createOrderTime": "2025-04-21 15:30:47",
      "timeout": 29,
      "payExpiredAt": "2025-04-21 15:59:47",
      "notifyUrl": "https://open-dbenefit-stage.dongfangfuli.com/openApi/customer/cash/callback/payNotify/azs",
      "returnUrl": "http://corp.m.stage.dongfangfuli.com/bfd-app/?union=azs",
      "goodsList": [
        {
          "goodsImg": "https://oss-scm-goods-prd.dongfangfuli.com/merchantSpu/picture/e399a137c6864e78892a14418744d50c.jpg",
          "quantity": 1,
          "goodsId": 2440928,
          "goodsPrice": 1.00,
          "goodsName": "商品2"
        }
      ],
      "consigneeInfo": {
        "consignee": "东福测试",
        "address": "IBP国际商务花园东区2号楼",
        "province": "上海市",
        "city": "上海",
        "street": "华阳路街道",
        "district": "长宁区",
        "mobile": "15011112222"
      }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 如果错误，返回错误信息。
data Object 订单信息

# Object属性

参数名称 参数类型 描述
orderNo String 客户的订单号
payUrl String 客户的收银台地址

# 3.2.2 支付成功通知

# 说明

1、接口由百福得提供，客户方支付成功后调用，用于通知百福得支付成功。

2、客户方应该支持通知失败时，间隔重复通知百福得，若客户方不支持，应当提供支付结果查询接口(参考3.2.4)，由东福补偿支付查询

# 地址

{东福域名}/openApi/customer/cash/callback/payNotify/{union}
客户方可以配置为固定的地址（对接时由东福提供），建议从3.2.1预下单接口取notifyUrl字段值

# HTTP请求方式

Request Method: POST Content-Type: application/json

# 公共参数(URL参数，参与签名)

字段 类型 是否必填 中文意描述
appId String 是 appId，由客户方提供
timestamp String 是 毫秒级时间戳 防止重复攻击
sign String 是 签名
version String 否 业务接口版本号，如1.0.0

# body参数（参与AES加密）

参数名称 参数类型 是否必须 描述
orderSn String 是 东福订单号

# 请求示例

POST //openApi/customer/cash/callback/payNotify/{union}?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
      "appId": "客户分配给东福的appId",
      "data": "密文"
}

---------------------------------注:密文对应的明文JSON示例---------------------------------
{
   "orderSn": "21250421153000105759"
}
1
2
3
4
5
6
7
8
9
10
11
12

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 如果错误，返回错误信息。
data Object 通知结果信息

# 3.2.3 退款接口

# 说明

1、接口由客户方提供，百福得调用，用于退还余额

2、相同退款单号，只能退款一次，接口应当支持幂等，一个订单可以有多次退款记录（此时会有多个退款单），退款单累计退款金额不能超过原订单金额

3、如果百福得调用积分退款接口失败(网络超时、系统错误等)，系统会触发退款补偿逻辑，系统在间隔半小时重试调用退款接口，共计5次

# 地址

接口由客户方提供

# HTTP请求方式

Request Method: POST Content-Type: application/json

# 公共参数(URL参数，参与签名)

字段 类型 是否必填 中文意描述
appId String 是 appId，由客户方提供
timestamp String 是 毫秒级时间戳 防止重复攻击
sign String 是 签名
version String 否 业务接口版本号，如1.0.0

# body参数（参与AES加密）

参数名称 参数类型 是否必须 描述
refundSn String 是 东福退款单号(幂等标识，唯一标识退款请求)
orderSn String 否 原东福订单号
tradeSn String 否 原交易流水号
refundAmount String 是 退款金额（单位分）
detail String 否 退款原因

# 明文请求示例

POST /cash/refund?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
      "appId": "客户分配给东福的appId",
      "data": "密文"
}

---------------------------------注:密文对应的明文JSON示例---------------------------------
{
    "refundSn": "317416754354806304870807118",
    "orderSn": "21250421153000105759",
    "tradeSn": "cust17452208162273009114084",
    "refundAmount": "300",
    "detail": "订单退款"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 如果错误，返回错误信息。
data Object 退款信息

# 3.2.4 支付状态查询接口【可选】

# 说明

1、接口由客户方提供，百福得调用，当支付通知东福失败时候，东福可以主动查询支付结果，防止客户方通知东福失败，而导致订单状态异常

2、若客户方不支持重试通知，应当提供支付结果查询接口，由东福补偿支付查询

# 地址

接口由客户方提供

# HTTP请求方式

Request Method: POST Content-Type: application/json

# 公共参数(URL参数，参与签名)

字段 类型 是否必填 中文意描述
appId String 是 appId，由客户方提供
timestamp String 是 毫秒级时间戳 防止重复攻击
sign String 是 签名
version String 否 业务接口版本号，如1.0.0

# body参数（参与AES加密）

参数名称 参数类型 是否必须 描述
orderSn String 是 东福订单号

# 明文请求示例

POST /payment/query?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
      "appId": "客户分配给东福的appId",
      "data": "密文"
}

---------------------------------注:密文对应的明文JSON示例---------------------------------
{
    "orderSn": "21250421153000105759"
}
1
2
3
4
5
6
7
8
9
10
11
12

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 如果错误，返回错误信息。
data Object 支付结果信息

# Object属性

参数名称 参数类型 描述
payStatus String 0待支付；1支付成功；2支付失败
payTime String 支付完成时间，yyyy-MM-dd HH:mm:ss
payAmount BigDecimal 支付金额

# 3.2.5 账户余额查询【可选】

# 说明

1、在东福收银台页面可以展示用户账户金额

# 地址

接口由客户方提供

# HTTP请求方式

Request Method: POST Content-Type: application/json

# 公共参数(URL参数，参与签名)

字段 类型 是否必填 中文意描述
appId String 是 appId，由客户方提供
timestamp String 是 毫秒级时间戳 防止重复攻击
sign String 是 签名
version String 否 业务接口版本号，如1.0.0

# body参数（参与AES加密）

参数名称 参数类型 是否必须 描述
account String 是 员工账号（条件必填），免密推送给东福的账号
externalNo String 否 客户系统用户唯一标识
costId String 否 活动场景，用于区分客户不同活动预算的标识

# 明文请求示例

POST /cash/queryAmount?appId=abc&timestamp=1597300776947&sign=fa66cb4d8604413b8fb30afd32e3e73e HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
      "appId": "客户分配给东福的appId",
      "data": "密文"
}

---------------------------------注:密文对应的明文JSON示例---------------------------------
{
   "externalNo": "zhangsan",
   "costId": "FL123456"
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 如果错误，返回错误信息。
data Object 账户余额信息

# Object属性

参数名称 参数类型 描述
costId String 活动预算Id
amount BigDecimal 账户余额

← 4.1 批量查询支付单明细→

Theme by Vdoing