Alipay+ DocsAlipay+ Docs

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

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 true.

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

copy
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

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 or U, the application startup is blocked and the MPP can troubleshoot the issue based on result codes and logs.

Sample

copy
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

Result

/

Request result, which contains information such as status and error codes. See Result for details.

M

Sample

copy
@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

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

copy
@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

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

copy
@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:

  • S: Success
  • F: Failed
  • U: Unknown

M

resultMessage

String

64

Result message that describes resultCode in detail

O