Payments SDK Prerequisites and Environment Setup

This guide outlines the environment setup and configuration steps required before integrating the AppInChina Payments SDK into your Android application.

caution

These steps are mandatory. The AppInChina SDK depends on the correct installation and configuration of the official WeChat Pay and Alipay SDKs.

Related docs

• Android SDK integration: Payments SDK Integration Guide for Android
• Login → Payments integration (identity mapping): Login → Payments integration (customer identity)
• Payments API reference (server-side): Payments API Reference
• Troubleshooting errors: Error Reference

1. Request your credentials

Getting your credentials is a single step. Contact our operations team once; we issue everything you need to start — both App IDs and the secret — together. You do not need to register anything with WeChat yourself.

Provide the following details:

• App name
• App package name (e.g., com.example.myapp)
• App signature (SHA1 and MD5 fingerprints of the release signing certificate)

Once reviewed, we register your app as a WeChat Open Platform Mobile Application in our WeChat developer account, bind the WeChat Pay merchant account, and issue all three values:

APP_ID:        [AppInChina App ID — provided by AppInChina]
APP_SECRET:    [AppInChina App Secret — provided by AppInChina]
WECHAT_APP_ID: [WeChat App ID — provided by AppInChina]

What each value is:

Credential	Used for
AppInChina App ID (APP_ID)	Authenticating SDK/API calls to the AppInChina IAP system.
AppInChina App Secret (APP_SECRET)	The secret paired with APP_ID. Keep server-side only.
WeChat App ID (wxAppId)	Initializing the WeChat SDK on-device (Section 2). This is your app's WeChat identity — the same App ID used for WeChat Login and Share — not a payment-specific ID.

Do not confuse the two App IDs

APP_ID (AppInChina) and wxAppId (WeChat) are separate identifiers from different platforms — even though AppInChina provides both to you. Using one where the other is expected is a common cause of initialization failures.

2. Install the WeChat Pay Android SDK

2.1 Add the WeChat SDK to your build.gradle

dependencies {
    compile 'com.tencent.mm.opensdk:wechat-sdk-android-with-mta:6.8.0'
}

2.2 Initialize IWXAPI in your app

private IWXAPI api;

private void initWechatPay(String wxAppId) {
    api = WXAPIFactory.createWXAPI(getApplicationContext(), wxAppId);
}

note

wxAppId is the WeChat App ID from Section 1 — not your AppInChina App ID (APP_ID).

2.3 WeChat integration troubleshooting

• Error: WeChat app not responding to payment request
  • Verify WeChat app is installed and up-to-date on the test device
  • Confirm the wxapi package name exactly matches your app's package name
  • Ensure WXPayEntryActivity is properly registered in AndroidManifest.xml
• Error: Payment initialization fails
  • Double-check your WeChat App ID format
  • Verify your app's signing certificate matches the one registered with AppInChina
  • Ensure the device has a stable network connection

3. Install the Alipay Android SDK

3.1 Add the Alipay SDK via Maven Central

Add the following dependency to your app-level build.gradle file:

dependencies {
    implementation 'com.alipay.sdk:alipaysdk-android:15.8.33'
}

3.2 Add the required FastJSON 1.x dependency

The Android Payments SDK artifact currently provided by AppInChina directly depends on legacy FastJSON 1.x (com.alibaba:fastjson) for JSON parsing. This dependency is required by the AppInChina Payments SDK itself — not only by Alipay — and it is not bundled in the SDK, so your app must supply it. If it is missing or the wrong version, payment initialization can crash with errors such as:

• NoClassDefFoundError: com/alibaba/fastjson/...
• ClassNotFoundException: com.alibaba.fastjson...

Include the exact pinned FastJSON 1.x version in your app-level build.gradle. Do not use a dynamic version selector such as + or "latest":

dependencies {
    implementation("com.alibaba:fastjson:1.2.83")

    // Only if the host app independently needs FastJSON2 (separate dependency family):
    // implementation("com.alibaba.fastjson2:fastjson2:<HOST_APP_PINNED_VERSION>")
}

FastJSON 1.x and FastJSON2 are different dependency families

com.alibaba:fastjson (FastJSON 1.x) and com.alibaba.fastjson2:fastjson2 (FastJSON2) have different package namespaces and are not interchangeable. The SDK uses FastJSON 1.x. If your project also pulls in FastJSON2 through another library, keep its version explicit and test the complete release dependency graph — do not replace the SDK's required FastJSON 1.x with FastJSON2 unless AppInChina publishes a newer SDK that explicitly supports it.

Why 1.2.83, and why any 1.2.x works

The Payments SDK uses only stable core FastJSON 1.x APIs (JSON.parseObject/parseArray to known classes, plus JSONObject/JSONArray getters) and does not use autotype deserialization. It therefore works with any FastJSON 1.2.x — the version is a security choice, not a compatibility constraint. Pin 1.2.83, the final and most-hardened 1.x release, which fixes the autotype RCE issues present in older builds. Do not ship an old version such as 1.1.70.android. All FastJSON 1.x is end-of-life; moving the SDK off 1.x is a separate item on our roadmap. See the compatibility matrix.

Inspecting your resolved FastJSON versions

Confirm which version Gradle actually packaged into your release graph (adapt the module/configuration names to your project):

./gradlew :app:dependencyInsight \
  --dependency com.alibaba:fastjson \
  --configuration releaseRuntimeClasspath

./gradlew :app:dependencyInsight \
  --dependency fastjson2 \
  --configuration releaseRuntimeClasspath

This is a diagnostic check — it identifies the version resolved into the release build. It does not by itself make a version supported. For FastJSON-related crash triage, see Troubleshooting → FastJSON.

3.3 Alipay integration troubleshooting

• Error: SDK initialization failure
  • Verify your AppInChina App ID (APP_ID) and App Secret (APP_SECRET) are correct
  • Check your network connection
  • Ensure all required permissions are properly declared in AndroidManifest.xml
• Error: Payment callback not received
  • Verify all required permissions are granted at runtime for Android 6.0+
  • Check if the device has sufficient storage space
  • Ensure Alipay app is installed and updated on the test device

4. Configure project repositories

Both the WeChat and Alipay SDKs are hosted on Maven Central. Be sure to include mavenCentral() in your root build.gradle file to ensure Gradle can resolve both dependencies correctly.

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

5. Declare required permissions

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

If targetSdkVersion >= 23, request the following permissions at runtime:

• WRITE_EXTERNAL_STORAGE
• READ_PHONE_STATE

6. Add WeChat queries entry (Android 11+)

If targetSdkVersion >= 30, add this section to your AndroidManifest.xml:

<queries>
    <package android:name="com.tencent.mm" />
</queries>

This ensures your app is allowed to query for the WeChat app when launching payment intents.

7. Implement the WeChat Pay callback activity

WeChat Pay requires your app to implement a callback receiver for payment results.

7.1 Create a wxapi package inside your app's base package

For example: com.yourcompany.yourapp.wxapi

7.2 Add WXPayEntryActivity class inside wxapi

public class WXPayEntryActivity extends Activity implements IWXAPIEventHandler {

    private IWXAPI api;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        api = com.mandou.acp.sdk.PayToolInfo.getApi();
        api.handleIntent(getIntent(), this);
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
        api.handleIntent(intent, this);
    }

    @Override
    public void onReq(BaseReq req) {
        // Handle request from WeChat if needed
    }

    @Override
    public void onResp(BaseResp resp) {
        // Handle WeChat payment response
        startActivity(new Intent(this, PayResultActivity.class));
        finish();
    }
}

note

The package name and class name must match exactly for WeChat to invoke it properly.

WXPayEntryActivity and the result Activity are different components

WXPayEntryActivity above is the WeChat callback receiver — it must live in a wxapi package with the exact naming WeChat requires. The PayResultActivity it launches is a separate, client-owned result Activity that the AppInChina SDK does not provide. You implement, declare, and package both. See Android SDK §7.4: the four post-payment components for the full component map.

8. Notes and important reminders

• These configurations are mandatory for payments to function.
• Failure to set up the WeChat or Alipay SDKs correctly will cause startPayment() calls to fail.
• Missing com.alibaba:fastjson can cause runtime crashes during Alipay initialization on some SDK combinations.
• The AppInChina SDK depends on these lower-level SDKs to open payment apps and receive callbacks.

Next: continue with the Android SDK integration guide.