1.版本
2. 关于本文档
目的
在本教程中,你将简要了解滴滴先买后付的后端 Java SDK。在学习过程中,你将:
-
掌握如何安装 Java SDK
-
了解请求滴滴先买后付需要的身份验证
-
了解如何使用 Java SDK 请求滴滴先买后付
人员
本文档适用于以下人员:
- 滴滴先享付(DiDi BNPL)内部相关产品、技术及运营团队;
- 所有与滴滴先享付开展业务合作的外部合作伙伴(以下简称“合作伙伴”),包括但不限于:
- 支付服务提供商(PSP);
- 电商平台;
- 各类持牌支付机构;
- 商户平台及其他接入方。
适用范围
本文档适用于所有已通过标准接口方式接入滴滴先享付(DiDi BNPL)的合作伙伴。
⚠️ 注意:对于采用定制化(非标)集成方案的合作伙伴,其接口设计与交互流程以双方另行签署的技术协议为准,不适用于本文档所述标准流程。
支持
如对本文档内容存在疑问,或在集成过程中遇到技术问题,请及时联系您的滴滴先享付对接负责人,或者邮箱联系:didipaylaternotice@didiglobal.com
3.环境要求
Java 1.8+
4.必需的密钥和参数
运行 SDK 需要以下信息,用于验证集成方的身份和环境:
-
clientId:客户端身份的唯一标识符,请通过“第2部分 DiDi BNPL合作伙伴配置和环境设置”进行获取。
-
clientSecret:配对的密钥,用于验证客户端的身份,请通过“第2部分 DiDi BNPL合作伙伴配置和环境设置”进行获取。(请严格保管好密钥,谨防泄露,丢失后只能重新申请,无法找回)
-
env:调用的环境,分为sandbox(沙箱环境)/ production(生产环境)(提供枚举类EnvEnum.class直接使用)
4.1 SDK 线下获取
获取DiDi BNPL后端SDK包
请按照如下模板发送邮件给DiDi来获取后端SDK包。
致: didipaylaternotice@didiglobal.com
标题:( 合作伙伴名称)-申请滴滴BNPL后端SDK包
正文:
亲爱的滴滴先买后付团队,
这是XXX (合作伙伴名称)。
我们正在与滴滴的先享后付功能进行集成。能否请您帮助我们分享滴滴BNPL后端SDK包?
谢谢。
此致敬礼。
4.2 SDK 线上获取
SDK包已上传至Maven Central
Artifact ID:didi-bnpl-server-sdk
Group ID:com.didifinance.sdk
Version:1.0.2
5.发起请求
以取消订单为例,向滴滴先买后付发起你的第一个请求:
public class FullExample {
public static void main(String[] args) throws ApiException {
//获取服务器
ApiClient client = new ApiClient("clientId", "clientSecret", EnvEnum.SANDBOX.getValue());
//获取sdk-api
DidiBnplApi didiBnplApi = new DidiBnplApi(client);
CancelOrderRequest cancelRequest = new CancelOrderRequest();
cancelRequest.setPartnerOrderId("mock-" + System.currentTimeMillis());
//发起请求
BaseVoidResponse cancel = didiBnplApi.cancelOrder(cancelRequest);
System.out.println("取消订单响应:" + cancel);
}
}
实践中推荐将client作为全局单例对象,避免重复创建,以下是一个使用示例:
1.注入配置
@Configuration
public class SDKConfig {
@Bean
public ApiClient apiClient() {
//注入client
//密钥尽量保存到安全的存储容器中,如KMS
return new ApiClient("clientId", "clientSecret", EnvEnum.SANDBOX.getValue());
}
@Bean
public DidiBnplApi didiBnplApi(ApiClient apiClient) {
//设置链接超时时(ms)
apiClient.setConnectTimeout(3000);
//设置读取超时时间(ms)
apiClient.setReadTimeout(3000);
//注入api
return new DidiBnplApi(apiClient);
}
}
2.调用api
@Slf4j
@RestController
@RequestMapping("/sdk")
public class SDKController {
@Autowired
private DidiBnplApi didiBnplApi;
@PostMapping("/checkOut")
public BaseOrderResponse checkOut(@RequestBody CheckOutRequest orderRequest) throws ApiException {
log.info("checkOut, request:{}", orderRequest);
BaseOrderResponse baseResponseAbstractOrderVO = didiBnplApi.checkOut(orderRequest);
log.info("checkOut, response:{}", baseResponseAbstractOrderVO);
return baseResponseAbstractOrderVO;
}
@PostMapping("/queryByPartnerOrderId")
public BaseOrderResponse queryByPartnerOrderId(@RequestBody QueryOrderResultRequest orderQueryByPartnerOrderIdRequest) throws ApiException {
log.info("queryByPartnerOrderId, request:{}", orderQueryByPartnerOrderIdRequest);
BaseOrderResponse orderQueryResponse = didiBnplApi.queryOrderResult(orderQueryByPartnerOrderIdRequest);
log.info("queryByPartnerOrderId, response:{}", orderQueryResponse);
return orderQueryResponse;
}
@PostMapping("/refund")
public RefundResponse refund(@RequestBody RefundRequest refundRequest) throws ApiException {
log.info("refund, request:{}", refundRequest);
RefundResponse refundResponse = didiBnplApi.refund(refundRequest);
log.info("refund, response:{}", refundResponse);
return refundResponse;
}
@PostMapping("/refundQuery")
public RefundQueryResponse refundQuery(@RequestBody QueryRefundResultRequest refundQueryRequest) throws ApiException {
log.info("refundQuery, request:{}", refundQueryRequest);
RefundQueryResponse refundQueryResponse = didiBnplApi.queryRefundResult(refundQueryRequest);
log.info("refundQuery, response:{}", refundQueryResponse);
return refundQueryResponse;
}
@PostMapping("/refundTrialPlan")
public TrialPlanRefundResponse trialPlan(@RequestBody TrialPlanRefundRequest refundTrialPlanRequest) throws ApiException {
log.info("refundTrialPlan, request:{}", refundTrialPlanRequest);
TrialPlanRefundResponse baseResponseRefundTrialPlanResponse = didiBnplApi.trialPlanRefund(refundTrialPlanRequest);
log.info("refundTrialPlan, response:{}", baseResponseRefundTrialPlanResponse);
return baseResponseRefundTrialPlanResponse;
}
@PostMapping("/cancel")
public BaseVoidResponse cancel(@RequestBody CancelOrderRequest cancelRequest) throws ApiException {
log.info("cancel, request:{}", cancelRequest);
BaseVoidResponse cancel = didiBnplApi.cancelOrder(cancelRequest);
log.info("cancel, response:{}", cancel);
return cancel;
}
}
6.当前支持的sdk接口方法
-
下单
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#checkOut
b. 入参:CheckOutRequest.class
c. 出参:BaseOrderResponse.class
-
取消订单
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#cancelOrder
b. 入参:CancelOrderRequest.class
c. 出参:BaseVoidResponse.class
-
查询下单结果
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryOrderResult
b. 入参:QueryOrderResultRequest.class
c. 出参:BaseOrderResponse.class
-
退款试算
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refundTrialPlan
b. 入参:TrialPlanRefundRequest.class
c. 出参:TrialPlanRefundResponse.class
-
退款
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refund
b. 入参:RefundRequest.class
c. 出参:RefundResponse.class
-
查询退款结果
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryRefundResult
b. 入参:QueryRefundResultRequest.class
c. 出参:RefundQueryResponse.class
-
预热
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#prescreen
b. 入参:PrescreenRequest.class
c. 出参:PrescreenResponse.class
-
查询还款信息
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#repayInfo
b. 入参:RepayInfoRequest.class
c. 出参:RepayInfoResponse.class