1.Version
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
-
Create Payment Order
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#checkOut
b. input parameter: CheckOutRequest.class
c. output parameter: BaseOrderResponse.class
-
Cancel Order
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#cancelOrder
b. input parameter: CancelOrderRequest.class
c. output parameter: BaseVoidResponse.class
-
Payment Order Information Query
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryOrderResult
b. input parameter: QueryOrderResultRequest.class
c. output parameter: BaseOrderResponse.class
-
Refund Simulation
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refundTrialPlan
b. input parameter: TrialPlanRefundRequest.class
c. output parameter: TrialPlanRefundResponse.class
-
Refund
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#refund
b. input parameter: RefundRequest.class
c. output parameter: RefundResponse.class
-
Refund Information Query
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#queryRefundResult
b. input parameter: QueryRefundResultRequest.class
c. output parameter: RefundQueryResponse.class
-
Prescreen
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#prescreen
b. input parameter: PrescreenRequest.class
c. output parameter: PrescreenResponse.class
-
Repayment Information Acquisition
a. com.didi.bnpl.sdk.client.api.DidiBnplApi#repayInfo
b. input parameter: RepayInfoRequest.class
c. output parameter: RepayInfoResponse.class