Alipay+ DocsAlipay+ Docs
APIs & SDKs

Quick start

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

Before you begin

The following requirements must be met:

  • Use JDK 6 or later.
  • Use Maven 3.3.9 or later if you integrate the SDK via Maven.

Step 1. Initialize POM

To initialize POM dependencies, complete the following steps:

  1. Log on to Alipay+ Developer Center to download 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>
  1. 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 Step 2. Initialize logging library.

Step 2. Initialize 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:

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

Step 3. Import 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"/>

Step 4. Define component properties

To define component properties, complete the following steps:

  1. Register your properties file by using XML or Java.

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();
    }
}
  1. 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.http.identify.socket-timeout=5000
ac.route.http.identify.connect-timeout=1000
ac.route.http.identify.connection-request-timeout=1000
ac.route.remote-identify-url=https://open-sea.alipayplus.com/api/open/common_form_data/extensions/identify/code.htm
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.

The Alipay+ server SDK first pulls the latest code rules from the Alipay+ route configuration server. If the pull fails, it loads the code rules stored in your local backup files. If the loading also fails, it 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.remote-identify-url

String

The URL through which the Alipay+ server SDK calls the Alipay+ server to identify the code and decode the code value

M

Provided by Alipay+.

The recommended default value is: https://open-sea.alipayplus.com/api/open/common_form_data/extensions/identify/code.htm

ac.route.http.identify.socket-timeout

int

The socket timeout for HTTP client in milliseconds when the Alipay+ server SDK calls the Alipay+ server to decode the code value

M

5000

ac.route.http.identify.connect-timeout

int

The connection timeout for HTTP client in milliseconds when the Alipay+ server SDK calls the Alipay+ server to decode the code value

M

1000

ac.route.http.identify.connection-request-timeout

int

The connection request timeout for HTTP client in milliseconds when the Alipay+ server SDK calls the Alipay+ server to decode the code value

M

1000

ac.route.client-id

String

The client ID of the MPP that is assigned by Alipay+

M

Note: The value assigned to this parameter in the production environment differs from the value used during acceptance testing. You can obtain the values from Alipay+ Developer Center.

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

ac.route.http.proxyHost

String

The HTTP proxy host used by Alipay+ server SDK when making requests to retrieve code rules or perform remote QR code identification

O

N/A

ac.route.http.proxyPort

int

The HTTP proxy port used by Alipay+ server SDK when making requests to retrieve code rules or perform remote QR code identification

O

N/A

ac.route.http.proxyScheme

String

The HTTP proxy scheme used by Alipay+ server SDK when making requests to retrieve code rules or perform remote QR code identification

O

N/A

ac.route.preset-file-path

String

The file path of a local backup file that contains code rules. When the ac.route.init-route-config-level parameter is set to PRESET, this parameter can be used to modify the file path

O

META-INF/route/default_config.json

Step 5. Initialize 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.

Step 6. Identify 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.

Learn more about

Home
Get Support
Need more help?