Alipay+ MPP Server SDK interfaces
This topic introduces the APIs and SPIs that are provided by Alipay+ Mobile Payment Partner Server SDK.
1. Overview
Alipay+ provides Mobile Payment Partners (MPPs) with APIs and SPIs for code identification.
1.1 APIs
The following table lists the APIs:
Interface | Type | Description |
ac.code.service.CodeIdentificationService#init | JVM | Code identification service initialization |
ac.code.service.CodeIdentificationService#identify | JVM | Identify codes that can be processed by Alipay+ |
1.2 SPIs
The following table lists the SPIs:
Interface | Type | Description |
ac.code.spi.RouteDataSpi#saveRouteConfigToLocal | JVM | Save route configurations to storage |
ac.code.spi.RouteDataSpi#readRouteConfigFromLocal | JVM | Read route configurations from storage |
ac.code.spi.RouteDataSpi#readRouteConfigFromRemote | JVM | Retrieve remote configurations |
2. APIs
This section describes the parameters, results, and samples of the APIs.
2.1 CodeIdentificationService#identify
When the MPP cannot recognize the code value, use this interface to check whether the code can be processed by Alipay+.
Parameters
Item | Type | Length | Description | Required |
request | CodeIdentificationIdentifyRequest | / | Code identification request | M |
CodeIdentificationIdentifyRequest
Item | Type | Length | Description | Required |
codeValue | String | 8192 | The code value that cannot be recognized by the MPP | M |
openId | String | >=3 | The parameter is used to identify whether the user is in the defined ratio or allowlist for the canary release. The value of openId must be related to the user ID, which can be userId or the hash value of userId. The value of openId is not sent to Alipay+. | M |
Result
CodeIdentificationIdentifyResult
Item | Type | Length | Description | Required |
result | / | Request result, which contains information such as status and error codes. See Result for details. | M | |
isAcCode | boolean | / | The parameter indicates whether the code can be processed by Alipay+. | M |
acDecodeConfig | String | 1024 | The parameter that is used by the Alipay+ client SDK to process the code. Note: Returned by Alipay+ if the value of the isAcCode parameter is | O |
Result code
resultCode | resultStatus | resultMessage |
SUCCESS | S | Success |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. |
UNKNOWN_EXCEPTION | U | The API calling failed because of unknown reasons. |
Result processing logic
- If result.resultStatus is
S
, the code identification is successful. See the following list for details:
- If isAcCode is
true
, the code can be processed by Alipay+ and the MPP must call the Alipay+ client SDK's API to process this code with acDecodeConfig specified. - If isAcCode is
false
, the code cannot be processed by Alipay+.
- If result.resultStatus is
F
, code identification failed. The MPP can handle the result based on result codes. - If result.resultStatus is
U
, unknown exceptions occur during the code identification and the MPP can check logs to view details. The MPP also might retry.
Sample
CodeIdentificationIdentifyRequest request = new CodeIdentificationIdentifyRequest();
request.setCodeValue("28100104df2342342****");
request.setOpenId("22877036828743438****");
CodeIdentificationIdentifyResult result = codeIdentificationService.identify(request);
if (result.getResult().getResultStatus().equals("S") && result.isAcCode()){
// the code should be processed by Alipay+
}
if (result.getResult().getResultStatus().equals("F"){
// Please pay attention to resultCode
}
2.2 CodeIdentificationService#init
Use this interface to initialize the code identification service when the system gets started. Call this interface to load route configuration data and schedule the updates of route configuration.
In the initialization process, the Alipay+ server SDK tries to load route configuration data from high-priority sources firstly, including remote server, local storage, and preset configuration. Once route configurations are loaded successfully, route configurations from lower-priority sources are not read. In addition, you can specify the minimum required level of the sources by the ac.route.init-route-config-level property. The initialization fails if loading from the minimum-level source fails.
It is recommended that you call this API during spring context initialization and block the application startup when the returned result is not SUCCESS
because the Alipay+ server SDK cannot make identifications when the SDK initialization failed. If you do not want to block the startup, the PRESET level might be set in the ac.route.init-route-config-level property to ensure that the SDK initialization is successful.
Parameters
N/A
Result
CodeIdentificationInitResult
Item | Type | Length | Description | Required |
result | / | Request result, which contains information such as status and error codes. See Result for details. | M |
Result code
resultCode | resultStatus | resultMessage |
SUCCESS | S | Success |
INIT_CONFIG_IS_INVALID | F | Initial configuration is invalid. |
REMOTE_CONFIG_UPDATE_FAILED | F | Remote configuration update failed. |
STORAGE_CONFIG_LOAD_FAILED | F | Loading storage configuration failed. |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. |
UNKNOWN_EXCEPTION | U | The API calling failed because of unknown reasons. |
Result processing logic
- If result.resultStatus is
S
, initialization is successful. - If result.resultStatus is
F
orU
, the application startup is blocked and the MPP can troubleshoot the issue based on result codes and logs.
Sample
CodeIdentificationInitResult result = codeIdentificationService.init();
if (result.getResult().getResultStatus().equals("S")){
// Initialization success.
} else {
// Block the application startup and troubleshoot
}
3. SPIs
This section describes the parameters, results, and samples of the SPIs.
3.1 RouteDataSpi#saveRouteConfigToLocal
The Alipay+ server SDK uses this interface to save route configuration data to storage.
When you implement this SPI, pay attention to the capacity limit of your storage because route configuration data contain all matching rules and the size can be as large as dozens of KBs. If you do not implement this SPI, the Alipay+ server SDK saves route configuration data to the local file at ac.route.save-route-config-path by default.
Parameters
Item | Type | Length | Description | Required |
request | SaveRouteConfigSpiRequest | / | Request of saving route configuration | M |
SaveRouteConfigSpiRequest
Item | Type | Length | Description | Required |
routeConfigData | String | 131072 | Route configuration data that contain all matching rules | M |
Result
SaveRouteConfigSpiResult
Item | Type | Length | Description | Required |
result | / | Request result, which contains information such as status and error codes. See Result for details. | M |
Sample
@Override
public SaveRouteConfigSpiResult saveRouteConfig(SaveRouteConfigSpiRequest request) {
String routeConfigData = request.getRouteConfigData();
SaveRouteConfigSpiResult result = new SaveRouteConfigSpiResult();
// save route config data to your storage and assemble the result
return result;
}
3.2 RouteDataSpi#readRouteConfigFromLocal
The Alipay+ server SDK uses this interface to read route configuration data from storage.
If you do not implement this SPI, the Alipay+ server SDK reads route configuration data from the local file at ac.route.save-route-config-path by default.
Parameters
Item | Type | Length | Description | Required |
request | ReadRouteConfigSpiRequest | / | Request of reading route configuration | M |
ReadRouteConfigSpiRequest
No parameters are defined in the model currently.
Result
ReadRouteConfigSpiResult
Item | Type | Length | Description | Required |
result | / | Request result, which contains information such as status and error codes. See Result for details. | M | |
routeConfigData | String | 131072 | Route configuration data. If route configuration data do not exist in the storage, null is returned in this parameter. | O |
Sample
@Override
public ReadRouteConfigSpiResult readRouteConfig(ReadRouteConfigSpiRequest request) {
ReadRouteConfigSpiResult result = new ReadRouteConfigSpiResult();
// read route config data from your storage and assemble the result
return result;
}
3.3 RouteDataSpi.readRouteConfigFromRemote
The Alipay+ server SDK uses this interface to retrieve remote route configuration data.
If you implement this SPI, the Alipay+ server SDK calls this interface regularly. The frequency of updating configurations depends on ac.route.pull-route-config-fixed-delay and ac.route.pull-route-config-exception-retry-delay.
If you do not implement this SPI, the Alipay+ server SDK regularly retrieves the remote configuration data by HTTP client and add the route configuration URI in the ac.route.pull-route-config-url.
Parameters
Item | Type | Length | Description | Required |
request | FetchRomoteRouteConfigSpiRequest | / | Request of retrieving route configurations | M |
FetchRomoteRouteConfigSpiRequest
Item | Type | Length | Description | Required |
uri | String | 4096 | Route configuration URI | M |
Result
FetchRemoteRouteConfigSpiResult
Item | Type | Length | Description | Required |
result | / | Request result, which contains information such as status and error codes. See Result for details. | M | |
routeConfigData | String | / | Remote route configuration data that contain all matching rules | O |
Sample
@Override
public ReadRouteConfigFromRemoteSpiResult readRouteConfigFromRemote(ReadRouteConfigFromRemoteSpiRequest request) {
// download file
String routeConfig = httpclient.get(request.getUri());
// assemble result
ReadRouteConfigFromRemoteSpiResult readRouteConfigFromRemoteSpiResult = new ReadRouteConfigFromRemoteSpiResult();
readRouteConfigFromRemoteSpiResult.setResult(MobileResultCode.SUCCESS.buildResult());
readRouteConfigFromRemoteSpiResult.setRouteConfigData(routeConfig);
return readRouteConfigFromRemoteSpiResult;
}
4. Result model
Result includes the following child parameters:
Item | Type | Length | Description | Required |
resultCode | String | 16 | Result code | M |
resultStatus | String | / | Result status. Valid values are:
| M |
resultMessage | String | 64 | Result message that describes | O |