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

3.1 积分支付示例

# 3.1 积分支付示例

# 说明

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

2、在东福收银台作为一种“支付方式”展示客户积分，用户选择“积分”用于支付抵扣，抵扣同步扣除用户积分

3、若积分全额抵扣，用户订单支付成功，若积分余额不足，先扣除用户积分后，然后跳转现金支付页面支付剩余金额

4、现金补差功能可根据客户开启和关闭

# 整体时序图

# 3.1.0 accessToken接口

1、由客户方提供，百福得调用，用于调用客户接口凭证，例如：积分查询、扣款、退款等接口

2、百福得调用access_token接口，客户方将返回的凭证缓存， 用于后续积分接口鉴权

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

4、需要注意凭证请求Content-Type 为 application/x-www-form-urlencoded

# 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是1.2示例中的出参，客户应当实现1.2凭证接口。

2、接口由客户方提供，百福得调用，实时查询员工的账户余额，externalNo是客户系统用户唯一标识，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、补偿查询是根据支付流水号查询支付结果，同时也会传递订单号和支付单号

# 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