百福得开放平台
  • 接口文档
  • 三、积分对接
2023-09-26
目录

3.1 积分支付示例

# 3.1 积分支付示例

# 说明

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

  2. 在东福收银台中，客户积分作为一种"支付方式"展示。用户选择"积分"进行支付抵扣时，系统将同步扣除用户积分。

  3. 若积分可全额抵扣订单金额，则订单支付成功；若积分余额不足，系统先扣除全部积分，然后跳转至现金支付页面支付剩余金额。

  4. 现金补差、东福福豆、福利卡支付等功能，可根据客户需求开启或关闭。

# 整体时序图

# ER图示例

# 3.1.0 accessToken接口

  1. 本接口由客户方提供，百福得调用，用于获取调用客户方接口的凭证，适用于积分查询、扣款、退款等接口。

  2. 百福得调用 access_token 接口后，客户方返回的凭证需进行缓存，用于后续积分接口的鉴权。

  3. Token 有效期正常情况下为 7200 秒（2 小时），百福得会提前 5 分钟将其标记为过期，失效时会重新获取 access_token。

  4. 请求凭证时，请注意 Content-Type 必须为 application/x-www-form-urlencoded。

  5. 重复请求将返回新的 access_token，历史凭证不会立即过期，将在缓存 2 小时后自然失效。

# HTTP请求方式

POST

# 公共参数

参数名称 参数类型 是否必须 描述
appId String 是 由百福得向客户方发放
grant_type String 是 固定值为 client_credential
timestamp String 是 毫秒级时间戳，以 Java 为例，取 System.currentTimeMillis()。百福得接口允许的毫秒级时间戳偏差为 5 分钟，偏差超过 5 分钟的请求将被拒绝（以服务器时间为准）。
sign String 是 签名
version String 否 业务接口版本号，如 1.0.0

# 请求示例

POST /access_token/create HTTP/1.1
Content-Type: application/x-www-form-urlencoded

appId=123456&grant_type=client_credential&sign=27e1f7ase213213ae2bf3672fd9101ba010a2434c119&timestamp=1620710648458
1
2
3
4

# 返回参数说明

参数名称 参数类型 描述
code String 返回码
msg String 错误时返回的错误信息
data TokenResponse 成功时返回的业务数据

# TokenResponse

参数名称 参数类型 描述
access_token String Token 访问令牌
expires_in Integer Token 的有效时长，单位：秒（s）

# 返回示例

{
  "code": 0,
  "data": {
    "access_token": "cde2c369fab499c0bf0643bb1844e70c",
    "expires_in": 7200
  },
  "msg": "OK"
}
1
2
3
4
5
6
7
8

# 3.1.1 积分余额查询

# 说明

  1. 本接口由客户方提供，百福得调用。积分接口入参中依赖的 access_token 为 3.1.0 accessToken接口 的返回参数，客户方需先实现该凭证接口。

  2. 本接口用于实时查询员工的账户余额。externalNo 为客户系统用户唯一标识，可与 account 相同或不同。account 更多是业务约定的账号，而 externalNo 可以是系统用户唯一 ID，可通过免密登录或用户推送传递给东福。

  3. 即使用户只有 1 个积分账户，接口返回的也是集合类型。不同积分可能对应不同权益，为方便后续业务扩展，若只有 1 个积分账户，双方可提前约定 externalPointType 的默认值。

# HTTP 请求方式

POST

# 公共参数

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

# Body 参数

字段 类型 是否必填 中文描述
externalNo String 是 客户系统用户唯一标识

# 请求示例

POST /pointQuery?access_token=efab39efas1dax&appId=abc&timestamp=1499932763&sign=5306a8d71d13c480df63d5e3f7e54d HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
   "externalNo": "7ad23229753615609dcf0639c2f56fd2885acc15"
}
1
2
3
4
5
6

# 返回参数说明

参数名称 参数类型 是否必填 描述
code String 是 返回码
msg String 是 错误时返回的错误信息
data PointQueryResponse 是 成功时返回的业务数据
# PointQueryResponse
参数名称 参数类型 是否必填 描述
amount Number 是 用户积分余额 （保留 2 位小数）
externalPointType String 条件必填（多积分账户时必填） 客户积分类型

# 返回示例

{
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "amount": 125.75,
      "externalPointType": "putongjifen"
    },
    {
      "amount": 10.12,
      "externalPointType": "fupinjifen"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 3.1.2 积分余额抵扣

# 说明

  1. 本接口由客户方提供，百福得调用，用于扣除员工积分以支付东福订单。

  2. 若百福得调用积分支付接口失败（如网络超时、系统错误等），系统将触发补偿逻辑，依赖 3.1.4 积分支付结果查询 接口查询支付结果。

  3. 补偿查询根据支付流水号查询支付结果。

  4. 一个订单可多次使用积分抵扣，请以支付流水号 tradeSn 作为支付标识，请勿使用 orderNo 或 orderSn。

# HTTP 请求方式

POST

# 公共参数

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

# Body 参数

字段 类型 是否必填 中文描述
externalNo String 是 客户系统用户唯一标识
amount Number 是 支付扣减金额 （保留 2 位小数）
tradeSn String 是 支付流水号，每次请求均有不同的流水号
orderNo String 否 订单号，订单详情页展示的单据号，可调用 4.2 查询订单详情信息
orderSn String 否 支付单号，与订单号为一对一关系，有支付超时概念，可调用 4.1 查询东福支付单
externalPointType String 条件必填（多积分账户时必填） 客户积分类型
remark String 否 支付描述

# 请求示例

POST /pointDeduction?access_token=efab39efas1dax&appId=abc&timestamp=1499932763&sign=5306a8d71d13c480df63d5e3f7e54d HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
	"externalNo": "7ad23229753615609dcf0639c2f56fd2885acc15",
	"amount": 10.52,
	"tradeSn": "bfd17035608616479212544790",
	"orderNo": "260203190001035378",
	"orderSn": "217701176814852230780430973",
	"externalPointType": "fupinjifen",
	"remark": "积分支付"
}
1
2
3
4
5
6
7
8
9
10
11
12

# 返回参数说明

参数名称 参数类型 是否必填 描述
code String 是 返回码
msg String 否 错误时返回的错误信息

# 返回示例

{
  "code": 0,
  "msg": "OK"
}
1
2
3
4
5

# 3.1.3 积分余额退款

# 退款逻辑

# 说明

  1. 本接口由客户方提供，百福得调用，用于退还员工积分。单笔订单支持部分多次退还或一次性全部退还。

  2. 客户方需通过 refundTradeSn 进行幂等校验（重复调用该接口时，code 需返回成功）。相同退款单重复请求应返回一致结果，一个退款流水号在客户系统内部只允许退还成功一次。

  3. 一个支付流水可对应多次退款记录（此时会产生多个退款流水），退款流水累计金额不能超过原支付流水金额。

  4. 若百福得调用积分退款接口失败（如网络超时、系统错误等），系统将触发退款补偿逻辑，间隔半小时重试调用退款接口，共计重试 5 次。

# HTTP 请求方式

POST

# 公共参数

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

# Body 参数

字段 类型 是否必填 中文描述
externalNo String 是 客户系统用户唯一标识
amount Number 是 退款金额 （保留 2 位小数）
refundTradeSn String 是 退款流水号，需要支持幂等
tradeSn String 是 原支付流水号
refundSn String 否 退款单号，一个退款单可包含多条退款流水
orderNo String 否 订单号，订单详情页展示的单据号，可调用 4.2 查询订单详情信息
orderSn String 否 支付单号，与订单号为一对一关系，有支付超时概念，可调用 4.1 查询东福支付单
remark String 否 退款描述

# 请求示例

POST /pointRefund?access_token=efab39efas1dax&appId=abc&timestamp=1499932763&sign=5306a8d71d13c480df63d5e3f7e54d HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
	"externalNo": "7ad23229753615609dcf0639c2f56fd2885acc15",
	"amount": 10.52,
	"refundTradeSn": "R1770118205327555631",
	"tradeSn": "bfd17701176901930321863744",
	"refundSn": "31770118205327053351",
	"orderNo": "260203190001035378",
	"orderSn": "217701176814852230780430973",
	"remark": "用户退款"
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 返回参数说明

参数名称 参数类型 是否必填 描述
code String 是 返回码
msg String 否 错误时返回的错误信息

# 返回示例

{
  "code": 0,
  "msg": "OK"
}
1
2
3
4
5

# 3.1.4 积分支付结果查询

# 说明

  1. 本接口由客户方提供，百福得调用，用于补偿查询支付失败的结果。

  2. 当百福得调用客户积分支付接口失败（通常是接口请求超时）时，通过该接口获取支付结果。

# HTTP 请求方式

POST

# 公共参数

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

# Body 参数

字段 类型 是否必填 中文描述
tradeSn String 是 支付流水号
externalPointType String 否 条件必填（多积分账户时必填）

# 请求示例

POST /resultQuery?access_token=efab39efas1dax&appId=abc&timestamp=1499932763&sign=5306a8d71d13c480df63d5e3f7e54d HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
	"tradeSn": "bfd17701176901930321863744",
	"externalPointType": "fupinjifen",
}
1
2
3
4
5
6
7

# 返回参数说明

参数名称 参数类型 是否必填 描述
code String 是 返回码
msg String 否 错误时返回的错误信息
data StatusResponse 是 成功时返回的业务数据
# StatusResponse
参数名称 参数类型 是否必填 描述
tradeSn String 是 支付流水号
txStatus String 是 支付结果：1 成功、2 失败

# 返回示例

{
  "code": 0,
  "data":{
    "tradeSn": "bfd17035608616479212544790",
    "txStatus": "1"
  },
  "msg": "OK"
}
1
2
3
4
5
6
7
8
9

← 3.2 客户收银台示例→

Theme by Vdoing