H Honor
ZH
DiDi finanzas

文档中心

提供接入指南、接口文档、测试指引等全流程接入所需信息

3. SDK Manual

1.版本

版本 版本内容 更新时间
V1.0 初始版本 2026-1-1
V1.1 在“5.Initiate a Request 发起请求”的“注入配置”中,添加“链接超时时间”的配置
"public DidiBnplApi didiBnplApi(ApiClient apiClient) {
        //设置链接超时时(ms)
        apiClient.setConnectTimeout(3000);
        ...... "
2026-3-18
V1.2
  • 新增 “4.2 SDK Online Obtain 线上获取”的内容。

  • “6.Currently Supported SDK API Methods 当前支持的sdk接口方法” 增加接口内容。
2026-4-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接口方法

  1. 下单

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#checkOut

    b. 入参:CheckOutRequest.class

    c. 出参:BaseOrderResponse.class

  2. 取消订单

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#cancelOrder

    b. 入参:CancelOrderRequest.class

    c. 出参:BaseVoidResponse.class

  3. 查询下单结果

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryOrderResult

    b. 入参:QueryOrderResultRequest.class

    c. 出参:BaseOrderResponse.class

  4. 退款试算

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refundTrialPlan

    b. 入参:TrialPlanRefundRequest.class

    c. 出参:TrialPlanRefundResponse.class

  5. 退款

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refund

    b. 入参:RefundRequest.class

    c. 出参:RefundResponse.class

  6. 查询退款结果

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryRefundResult

    b. 入参:QueryRefundResultRequest.class

    c. 出参:RefundQueryResponse.class

  7. 预热

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#prescreen

    b. 入参:PrescreenRequest.class

    c. 出参:PrescreenResponse.class

  8. 查询还款信息 

    a. com.didi.bnpl.sdk.client.api.DidiBnplApi#repayInfo

    b. 入参:RepayInfoRequest.class

    c. 出参:RepayInfoResponse.class

复制成功