Alipay+ DocsAlipay+ Docs
APIs & SDKs

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:

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

  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>
  1. Add your custom Log4j2 configuration file to the classpath. The following configuration is a sample that prints logs to the console. The actual logging configuration depends on your project. See Configuration for details.
copy
<?xml version="1.0" encoding="UTF-8"?>
<!--Sample Log4j2 configuration which just print logs to the console.-->
<Configuration>
    <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>

    </Appenders>

    <Loggers>
        <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:

  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=STORAGE
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+>

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 route configurations 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 minimum required level of the loaded route configurations when initializing the Alipay+ server SDK. The initialization fails if the minimum-level configurations fail to be loaded. Valid values are:

  • REMOTE: remote server
  • STORAGE: local storage

M

Decided by the MPP.

REMOTE is useful if loaded route configurations are always the latest. STORAGE is useful if custom storage implementation is used and the loaded configurations are at least from storage. It is recommended that you put the configuration file into storage before initialization.

ac.route.pull-route-config-fixed-delay

int

Interval of pulling route configurations in minutes

M

10

ac.route.pull-route-config-exception-retry-delay

int

Retry interval of pulling route configurations in minutes

M

2

ac.route.save-route-config-path

String

Path where pulled route configurations 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.

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.

Learn more about

Home
Get Support
Need more help?