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

3.2 客户收银台示例

# 3.2 客户收银台示例

# 说明

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

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

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

# 整体时序图

# 签名与加密

  1. appId、appSecret 由客户方提供，签名和加密共用同一个密钥。密钥长度为 128 位（16 字节），示例：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
  1. 接口传输统一使用 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