Quickstart

This topic shows how to integrate Alipay+ MPP Server SDK with your server.

Before you begin

The following requirements must be met:

JDK 6 or higher.
Maven 3.3.9 or higher if you integrate the SDK via Maven.

Get started

1 Initializing POM

To initialize POM dependencies, complete the following steps:

Contact your solution architect to obtain the SDK JAR file. If you use a private Maven repository manager like Nexus, upload the downloaded JAR file to your repository. Refer to the following sample for details on how to upload the file. Replace placeholders as required.

copy
mvn deploy:deploy-file \
  -DgroupId=com.alipayconnect.mobile \
  -DartifactId=mpp-server-sdk \
  -Dversion=<mpp-server-sdk-version> \
  -Dpackaging=jar \
  -Dfile=<path-to-jar-file> \
  -DrepositoryId=<id-to-map-on-server-section-of-settings.xml> \
  -Durl=<url-of-the-repository-to-deploy>

Download POM dependencies from Maven. Refer to the following sample for details on how to download POM dependencies from Maven. The minimum required versions of open source dependencies are listed in the sample.

copy
<!--Component dependencies-->
<dependency>
    <groupId>com.alipayconnect.mobile</groupId>
    <artifactId>mpp-server-sdk</artifactId>
    <version>${mpp.server.sdk.version}</version>
</dependency>
<dependency>
    <groupId>com.alipayconnect.mobile</groupId>
    <artifactId>mpp-server-sdk-framework</artifactId>
    <version>${mpp.server.sdk.framework.version}</version>
</dependency>

<!--Open source dependencies-->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <!--Minimum version: 4.3.4.RELEASE-->
    <version>5.3.20</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <!--Minimum version: 1.7.0-->
    <version>1.7.9</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <!--Minimum version: 1.2.51.sec09-->
    <version>1.2.83</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <!--Minimum version: 3.7-->
    <version>3.8.1</version>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <!--Minimum version: 4.4.1-->
    <version>4.5.8</version>
    <exclusions>
        <exclusion>
            <artifactId>commons-logging</artifactId>
            <groupId>commons-logging</groupId>
        </exclusion>
    </exclusions>
</dependency>

<!-- https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api -->
 <dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>

<!-- https://mvnrepository.com/artifact/javax.annotation/javax.annotation-api -->
<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version>
</dependency>

<!--Logging library dependencies. See next section-->

Note: Logging library dependencies are not included in the sample. For more information about logging library dependencies, see 2.2.2 Initializing logging library.

2 Initializing logging library

Based on SLF4J, MPP developers can use a custom logging library. Refer to the following samples for details on how to initialize the Log4j2 logging library, which is an option provided by Alipay+. The MPP can also choose other logging libraries.

To initialize the Log4j2 logging library, complete the following steps:

Add Log4j2 dependencies to your project.

copy
<!--Log4j2 dependencies-->
<!-- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-core -->
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.17.1</version>
</dependency>

<!-- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-api -->
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.17.1</version>
</dependency>

<!-- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-slf4j-impl -->
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j-impl</artifactId>
  <version>2.17.1</version>
</dependency>

<dependency>
    <groupId>com.lmax</groupId>
    <artifactId>disruptor</artifactId>
    <version>3.4.2</version>
</dependency>

Add your custom Log4j2 configuration file to the classpath and configure the LOG_PATH property to specify the path on which the log files are kept. For more information about the log files, see Log file locations. For the setting of the LOG_PATH property, application represents the application.properties file; config/application represents the path to the classpath:config/application.properties file. The value of ac.log.path property can be read from the application.properties file.

The following configuration is a sample that prints logs. The actual logging configuration depends on your project. See
Configuration for details.

copy
<?xml version="1.0" encoding="UTF-8"?>

<Configuration status="WARN">

    <Properties>
        <property name="LOG_PATH">${bundle:config/application:ac.log.path}</property>
    </Properties>

    <Appenders>

        <Console name="STDOUT-APPENDER" target="SYSTEM_OUT">
            <PatternLayout pattern="%-5p %c{2} - %m%n%throwable" charset="UTF-8"/>
        </Console>

        <Console name="STDERR-APPENDER" target="SYSTEM_ERR">
            <PatternLayout pattern="%-5p %c{2} - %m%n%throwable" charset="UTF-8"/>
        </Console>

        <RollingFile name="CODE-IDENTIFICATION-SERVICE-APPENDER" fileName="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-identification.log"
                     filePattern="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-identification.log.%d{yyyy-MM-dd}"
                     append="true">
            <PatternLayout
                    pattern="%d %-5p %c{2} - %m%n%throwable"
                    charset="UTF-8"/>
            <TimeBasedTriggeringPolicy/>
            <DefaultRolloverStrategy/>
        </RollingFile>

        <RollingFile name="CODE-SCHEDULER-SERVICE-APPENDER" fileName="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-scheduler.log"
                     filePattern="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-scheduler.log.%d{yyyy-MM-dd}"
                     append="true">
            <PatternLayout
                    pattern="%d %-5p %c{2} - %m%n%throwable"
                    charset="UTF-8"/>
            <TimeBasedTriggeringPolicy/>
            <DefaultRolloverStrategy/>
        </RollingFile>

        <RollingFile name="ERROR-APPENDER" fileName="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-error.log"
                     filePattern="${LOG_PATH}/alipayplus-code-rule/alipayplus-code-error.log.%d{yyyy-MM-dd}"
                     append="true">
            <PatternLayout
                    pattern="%d %-5p %c{2} - %m%n%throwable"
                    charset="UTF-8"/>
            <TimeBasedTriggeringPolicy/>
            <DefaultRolloverStrategy/>
            <ThresholdFilter level="ERROR"/>
        </RollingFile>

    </Appenders>

    <Loggers>

        <AsyncLogger name="CODE-IDENTIFICATION-SERVICE" additivity="false" level="info">
            <AppenderRef ref="CODE-IDENTIFICATION-SERVICE-APPENDER"/>
            <AppenderRef ref="ERROR-APPENDER"/>
        </AsyncLogger>

        <AsyncLogger name="CODE-SCHEDULER-SERVICE" additivity="false" level="info">
            <AppenderRef ref="CODE-SCHEDULER-SERVICE-APPENDER"/>
            <AppenderRef ref="ERROR-APPENDER"/>
        </AsyncLogger>

        <AsyncLogger name="STDOUT" additivity="false" level="info">
            <AppenderRef ref="STDOUT-APPENDER"/>
        </AsyncLogger>

        <AsyncLogger name="STDERR" additivity="false" level="info">
            <AppenderRef ref="STDERR-APPENDER"/>
        </AsyncLogger>

        <AsyncRoot level="info">
            <AppenderRef ref="STDOUT-APPENDER"/>
        </AsyncRoot>

    </Loggers>
</Configuration>

3 Importing bean definitions from components

To import bean definitions from the Alipay+ server SDK, use the following configuration files:

File Name	Description
component-server-sdk.xml	Component beans.

Sample code:

copy
<import resource="classpath:/META-INF/config/component-server-sdk.xml"/>

4 Defining component properties

To define component properties, complete the following steps:

Sample code for XML:

copy
<context:property-placeholder location="classpath:ac-sdk.properties" />

Sample code for Java:

copy
@PropertySource("classpath:ac-sdk.properties")
@Configuration
public class AcSdkConfig {

    @Bean
    public PropertySourcesPlaceholderConfigurer propertySourcesPlaceholderConfigurer() {
        return new PropertySourcesPlaceholderConfigurer();
    }
}

Add component properties.

copy
ac.route.pull-route-config-url=<route-config-http-server-url>
ac.route.init-route-config-level=PRESET
ac.route.pull-route-config-fixed-delay=10
ac.route.pull-route-config-exception-retry-delay=2
ac.route.save-route-config-path=/home/admin/ac-sdk/
ac.route.http.socket-timeout=3000
ac.route.http.connect-timeout=3000
ac.route.http.connection-request-timeout=3000
ac.route.mode=<type-of-environment>
ac.route.client-id=<client-ID-assigned-by-Alipay+>
ac.log.path=<code-rule-log-path>

The following table shows all component properties in detail:

Property	Type	Description	Required	Suggested value
ac.route.pull-route-config-url	String	HTTP server URL where the code rules are downloaded	M	Provided by Alipay+. The recommended default value is https://open-sea.alipayplus.com/aps/api/v1/codes/inquiryCodeRules.
ac.route.init-route-config-level	String	The mode of initiating Alipay+ server SDK	M	Set the value to `PRESET`. Your server side first pulls the latest code rules from the Alipay+ server SDK. If the pull fails, you load the code rules stored in your local backup files. If the loading also fails, you can obtain the local code rules preset in the jar file.
ac.route.pull-route-config-fixed-delay	int	Interval of pulling code rules in minutes	M	10
ac.route.pull-route-config-exception-retry-delay	int	Retry interval of pulling code rules in minutes	M	2
ac.route.save-route-config-path	String	Path where pulled code rules are saved	M	Decided by the MPP. Example: `/home/admin/ac-sdk/`
ac.route.http.socket-timeout	int	Socket timeout for HTTP client in milliseconds	M	3000
ac.route.http.connect-timeout	int	Connection timeout for HTTP client in milliseconds	M	3000
ac.route.http.connection-request-timeout	int	Connection request timeout for HTTP client in milliseconds	M	3000
ac.route.mode	String	The type of environment where the SDK is called	M	Valid values are: `PROD`: indicates the production environment. `SHADOW`: indicates the acceptance testing environment. Note: Set the value to `SHADOW` during acceptance testing.
ac.route.client-id	String	The client ID of the MPP that is assigned by Alipay+	M	Note: The value of this parameter must be prefixed with "TEST_" during acceptance testing.
ac.log.path	String	The path on which the log files are kept	M	The default value is `./logs` Note: If the default value is used, the default log path is `./logs/alipayplus-code-rule/`.

5 Initializing components

Use the following API to initialize components before identifying codes. For more information, see CodeIdentificationService#init.

API	Description
ac.code.service.CodeIdentificationService#init	Initialize the code identification service.

6 Identifying codes

When the MPP cannot recognize the code value, use the following API to check whether the code can be processed by Alipay+. For more information, see CodeIdentificationService#identifyCode.

API	Description
ac.code.service.CodeIdentificationService#identifyCode	Identify codes that can be processed by Alipay+.

Next steps

After you have integrated the SDK, you can move on to use the SDK in different payment scenarios.

For more information about how to use the SDK in Cashier Payment, see Cashier Payment integration.

For more information about how to use the SDK in Merchant-presented Mode Payment, see Merchant-presented Mode Payment integration.