H Honor
EN
DiDi finanzas

Documentation

Provides integration guides, API documentation, testing instructions and other information needed throughout the integration process

3. SDK Manual

1.Version

Version Version Content Update time
V1.0 Initial Version 2026-1-1
V1.1 in "5.Initiate a Request" under "Inject Configuration", add a "link timeout" configuration.
"public DidiBnplApi didiBnplApi(ApiClient apiClient) {
        // Set link timeout (ms)
        apiClient.setConnectTimeout(3000);
        ...... "
2026-3-18
V1.2
  • Add the content of "4.2 SDK Online Obtain".

  • "6.Currently Supported SDK API Methods" Add interface content.
2026-4-1

2.About this Document

Purpose

In this tutorial, you will get a brief introduction to DiDi's BNPL (Buy Now, Pay Later) backend Java SDK. During the learning process, you will:

  • Master how to install the Java SDK

  • Understand the authentication required to request DiDi's BNPL service

  • Learn how to use the Java SDK to call DiDi's BNPL service

Audience

The audience of this document is DiDi BNPL staff and DiDi BNPL cooperating partner (hereafter referred to as partner) , including PSP, e-commerce platform, or various types of payment partner and merchant platform staff.

Application Scope

This document applies to all DiDi BNPL cooperating partner (hereafter referred to as partner) except for partners that have been integrated through custom (non-standard) integration methods.

Support

Please address your questions to your DiDi BNPL  Account Manager, or email: didipaylaternotice@didiglobal.com

3.Environment Requirement 

Java 1.8+

4.Necessary Secret and Parameter

The following information is required to run the SDK for verifying the integrator’s identity and environment:

  • clientId: Unique identifier for the client. Please obtain it from Part II DiDi BNPL Env. Setup.

  • clientSecret: Paired secret key used for client authentication. Please obtain it from Part II DiDi BNPL Env. Setup. (Keep the secret key strictly confidential to prevent disclosure. If lost, it can only be re-applied for and cannot be recovered.)

  • env: Target environment for invocation, including sandbox and production. (The enumeration class EnvEnum.class is provided for direct use.)

4.1 SDK Offline Obtain

Obtain the DiDi BNPL Backend SDK

Pls send the email to get the SDK package.

To: didipaylaternotice@didiglobal.com
Title: (Partner name) - Apply for DiDi BNPL Backend SDK package
Main Body:


Dear DiDi BNPL Team,

This is XXX (Partner name).

We're integrating with DiDi BNPL function. Could you please help to share us the DiDi BNPL Backend SDK package?


Thank you.
Best regards.

4.2 SDK Online Obtain 

 The SDK package has been uploaded to Maven Central.

Artifact ID:didi-bnpl-server-sdk

Group ID:com.didifinance.sdk

Version:1.0.2

5.Initiate a Request 

Take order cancellation as an example to send your first request to DiDi BNPL:

public class FullExample {
    public static void main(String[] args) throws ApiException {
        //Obtain the server
        ApiClient client = new ApiClient("clientId", "clientSecret", EnvEnum.SANDBOX.getValue());
        //Obtain sdk-api
        DidiBnplApi didiBnplApi = new DidiBnplApi(client);
        
        CancelOrderRequest cancelRequest = new CancelOrderRequest();
        cancelRequest.setPartnerOrderId("mock-" + System.currentTimeMillis());
        //Initiate a request
        BaseVoidResponse cancel = didiBnplApi.cancelOrder(cancelRequest);
        System.out.println("cancel Order Response: " + cancel);
    }
}

In practice, it is recommended to use the client as a global singleton object to avoid repeated creation. Below is a usage example:

1.Inject the configuration

@Configuration
public class SDKConfig {
    @Bean
    public ApiClient apiClient() {
        //Inject the client
        //Try to save the key in a secure storage container, such as KMS
        return new ApiClient("clientId", "clientSecret",  EnvEnum.SANDBOX.getValue());
    }

    @Bean
    public DidiBnplApi didiBnplApi(ApiClient apiClient) {
        //Set link timeout (ms)
        apiClient.setConnectTimeout(3000);
        //Set the read timeout (ms)
        apiClient.setReadTimeout(3000);
        //Inject api
        return new DidiBnplApi(apiClient);
    }
}

2.Invoke the 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.Currently Supported SDK API Methods

  1. Create Payment Order 

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

    b. input parameter: CheckOutRequest.class

    c. output parameter: BaseOrderResponse.class

  2. Cancel Order 

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

    b. input parameter: CancelOrderRequest.class

    c. output parameter: BaseVoidResponse.class

  3. Payment Order Information Query 

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

    b. input parameter: QueryOrderResultRequest.class

    c. output parameter: BaseOrderResponse.class

  4. Refund Simulation 

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

    b. input parameter: TrialPlanRefundRequest.class

    c. output parameter: TrialPlanRefundResponse.class

  5. Refund 

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

    b. input parameter: RefundRequest.class

    c. output parameter: RefundResponse.class

  6. Refund Information Query 

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

    b. input parameter: QueryRefundResultRequest.class

    c. output parameter: RefundQueryResponse.class

  7. Prescreen 

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

    b. input parameter: PrescreenRequest.class

    c. output parameter: PrescreenResponse.class

  8. Repayment Information Acquisition 

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

    b. input parameter: RepayInfoRequest.class

    c. output parameter: RepayInfoResponse.class

Copied successfully