Payments API Reference (Endpoints and Parameters)

1. Authentication and base URL

To use the AppInChina Payments API, all requests must include authentication headers that identify your application.

1.1 Required headers

Each request must include the following two headers:

Header	Description
`APP_ID`	Your application’s unique identifier, provided by AppInChina.
`APP_SECRET`	The secret key associated with your APP_ID. Keep this value secure and do not expose it in client-side code.

Example (Java)

private static final String APP_ID = "your_app_id_here";
private static final String APP_SECRET = "your_app_secret_here";

private static final Headers headers = Headers.of(
    "APP_ID", APP_ID,
    "APP_SECRET", APP_SECRET
);

caution

Keep your APP_SECRET confidential. Do not include it in frontend code or expose it in logs or error messages.

Identity mapping (customerIdentity): Login → Payments integration (customer identity)
High-level flow: Understanding the IAP SDK/API Flow
Android SDK guide: Payments SDK Integration Guide for Android
PC & H5 guide: PC and H5 Payments Integration Guide
Troubleshooting errors: Error Reference

1.2 Base URL

All API requests should be made to the following base URL:

https://api.appinchinaservices.com

You will append specific endpoints (such as /order.json, /detail.json, etc.) to this base URL.

2. Pay channel initialization

2.1 Endpoint

GET /payTools.json

This endpoint retrieves a list of payment channels (e.g., WeChat Pay, Alipay) that are available and signed for your application. It is typically used to dynamically determine which payment methods should be shown to the user during checkout.

2.2 Purpose

Use this endpoint to:

Determine whether WeChat Pay and/or Alipay are available.
Identify the configured environment (DEV or PROD) for each channel.
Validate whether the required payment credentials are properly set up (signStatus).

2.3 Required headers

Authentication headers (APP_ID and APP_SECRET) must be included in the request.

See Authentication and base URL for details.

2.4 Successful response

{
  "msg": "success",
  "code": 0,
  "data": [
    {
      "accountId": "exampleAccountId",
      "appEnv": "PROD",
      "appName": "MyApp",
      "appPackageName": "com.example.myapp",
      "appSignature": "hash",
      "extInfo": {},
      "gmtCreate": 1551099989000,
      "gmtModified": 1551099989000,
      "id": "payToolId123",
      "payChannel": "WECHAT",
      "signStatus": "OK"
    }
  ]
}

Key fields

Field	Description
`payChannel`	Payment method: `WECHAT` or `ALIPAY`
`signStatus`	Indicates whether the payment method is properly configured: `OK` or `NO`
`appEnv`	Application environment: `DEV` or `PROD`
`appName` / `appPackageName`	App metadata used to identify the registered app
`gmtCreate` / `gmtModified`	Timestamps (in milliseconds) of record creation/modification

tip

Only show payment methods where signStatus == "OK" and appEnv == "PROD" to real users.

2.5 Error response

{
  "code": "error_code",
  "msg": "error_message"
}

3. Create order

3.1 Endpoint

POST /order.json

This endpoint is used to create a new payment order.

It generates the necessary information to initiate a payment with either WeChat Pay or Alipay, depending on the selected payment channel and environment.

3.2 Purpose

Use this endpoint to:

Create a unique payment order for a user transaction.
Initiate payment through the appropriate channel (WeChat or Alipay).
Receive parameters needed to proceed with payment (e.g., prepayid, sign, etc. for WeChat).

3.3 Required headers

Authentication headers (APP_ID and APP_SECRET) must be included in the request.

See Authentication and base URL for details.

3.4 Request parameters

Parameter	Type	Required	Description
`amount`	`long`	Required	Payment amount in cents. (e.g., 100 = ¥1 RMB)
`bizNo`	`string`	Required	Unique transaction number generated by the client for internal record keeping.
`goodsTitle`	`string`	Required	Title or description of the item being purchased (displayed during payment).
`payChannel`	`string`	Required	Payment channel: `WECHAT` or `ALIPAY`.
`paySource`	`string`	Optional	Payment source: `NATIVE`, `H5`, or `APP`. (Default is `APP` if not specified.)
`customerIdentity`	`string`	Recommended	User identifier, useful for linking payments to accounts. See Login → Payments integration (customer identity).
`customerName`	`string`	Recommended	User's username, phone number, or other human-readable identifier.
`serviceNo`	`string`	Deprecated	Service order number tied to subscription or timed services.
`serviceTypeNo`	`string`	Deprecated	Service type identifier created in the AppInChina Dashboard.
`attachData`	`string`	Optional	Additional metadata to associate with the order (custom JSON string or plain text). If you use the Android SDK, you may provide a key/value map which the SDK serializes for you.
`sourceFrom`	`string`	Optional	Identifier of the app store where the payment was initiated (see below for accepted values).

3.4.1 Using `attachData` effectively

attachData is your order metadata field. AppInChina Payments records it with the transaction and returns it back in order query responses (for example /detail.json and /history.json).

Use it when you need more than “a transaction happened” — for example, to connect payments to:

Your SKU / product ID
Subscription plan ID / tier
A promo / campaign identifier
A pricing version (useful for A/B tests or regional price tables)
Any internal IDs your backend needs to reconcile and fulfill correctly

Recommended format

Keep it small and stable.
Prefer a compact JSON object encoded as a string (or plain text if you prefer).
If you use the Android SDK, you can pass a key/value map and the SDK serializes it.

Security and privacy

Do not store secrets (tokens, API keys) in attachData.
Avoid raw PII when possible (phone, email, full name).
Treat attachData as metadata for reporting/reconciliation — not as an authorization mechanism.

Example (CreateOrder request body)

{
  "amount": 999,
  "bizNo": "ORDER_20260205_0001",
  "goodsTitle": "Pro plan (3 months)",
  "payChannel": "WECHAT",
  "customerIdentity": "user_12345",
  "attachData": "{\"productId\":\"pro_3m\",\"promoId\":\"winter25\",\"priceVersion\":\"v3\"}"
}

Accepted values for `sourceFrom`

App Store	Value
Tencent MyApp	`tencent`
Huawei App Market	`huawei`
Oppo Software Store	`oppo`
360 Mobile Assistant	`360`
Baidu Mobile Assistant / 91 Assistant / Himarket	`baidu`
MIUI App Store	`miui`
VIVO App Store	`vivo`
PP Assistant / Wandoujia / Taobao	`pp`
China Mobile MM Store	`chinamm`
Anzhi Market	`anzhi`
Sogou Mobile Assistant	`sogou`
Meizu Flyme	`meizu`
Coolpad	`coolpad`
Lenovo Store	`lenovo`
Samsung App Store	`samsung`
AppChina	`appchina`
Others	`others`

3.5 Successful response examples

WeChat Pay example

{
  "msg": "success",
  "traceId": "b7c04e1317476299292752036",
  "code": 0,
  "data": {
    "appid": "wxappidexample",
    "noncestr": "randomString",
    "package": "Sign=WXPay",
    "partnerid": "wechatPartnerId",
    "prepayid": "wechatPrepayId",
    "sign": "generatedSignature",
    "timestamp": 1747629929
  }
}

Alipay example

{
  "msg": "success",
  "traceId": "b7c04e1317476298157356165",
  "code": 0,
  "data": {
    "app_id": "2021001156621375",
    "biz_content": "{\"body\":\"1\",\"out_trade_no\":\"20250519000916970200108462\",\"product_code\":\"QUICK_MSECURITY_PAY\",\"subject\":\"1\",\"total_amount\":\"0.01\"}",
    "charset": "utf-8",
    "format": "json",
    "method": "alipay.trade.app.pay",
    "notify_url": "https://api.appinchinaservices.com/payBackAlipay",
    "return_url": "https://api.appinchinaservices.com/payBackAlipay",
    "sign": "...",
    "sign_type": "RSA2",
    "timestamp": "2025-05-19 12:43:35",
    "version": "1.0"
  },
  "message": "success"
}

3.6 Error response

{
  "code": "error_code",
  "msg": "error_message"
}

4. Query single order

4.1 Endpoint

GET /detail.json

This endpoint retrieves the details of a specific payment order using the transaction identifier (bizNo) and the associated user identity (customerIdentity).

4.2 Request parameters

Parameter	Type	Required	Description
`bizNo`	`string`	Required	The unique order identifier originally passed to the CreateOrder API.
`customerIdentity`	`string`	Required	The identifier for the customer who initiated the order. This is used to prevent unauthorized order queries.

4.3 Successful response

{
  "msg": "success",
  "code": 0,
  "data": {
    "amount": 1,
    "appId": "yourAppId",
    "bizNo": "uniqueTransactionId",
    "extInfo": {},
    "gmtCreate": 1551676154000,
    "gmtModified": 1551676154000,
    "pmtDt": 1551676154000,
    "attachData": {},
    "sourceFrom": "huawei",
    "goodsTitle": "Premium subscription 3 months",
    "id": "orderId",
    "payChannel": "WECHAT",
    "paymentStatus": "PAID"
  }
}

Key fields

Field	Description
`amount`	Payment amount in cents.
`bizNo`	Client-generated unique transaction number.
`paymentStatus`	`PAID` means payment completed successfully. Other values may include `PENDING`, `CLOSE`, `REFUND`.
`pmtDt`	Payment timestamp (if completed).
`goodsTitle`	Description of the purchased item.
`payChannel`	Payment channel used (`WECHAT` or `ALIPAY`).
`sourceFrom`	App store identifier, if provided during order creation.
`attachData`	Any custom metadata sent with the original order.
`extInfo`	Reserved for platform use.

tip

Always treat a payment as successful only if paymentStatus === "PAID".

5. Query order list

5.1 Endpoint

GET /history.json

This endpoint retrieves a paginated list of historical payment orders associated with a given customer.

5.2 Request parameters

Parameter	Type	Required	Description
`customerIdentity`	`string`	✅	Unique identifier of the customer whose order history is being queried
`paymentStatus`	`string`	Optional	Filter by status: `PAID`, `PENDING`, `CLOSE`, `REFUND`, etc.
`pageNum`	`number`	Optional	Page number to retrieve (default: `1`)
`pageSize`	`number`	Optional	Number of records per page (default: `20`)

5.3 Successful response

{
  "msg": "success",
  "code": 0,
  "data": {
    "payOrderList": [
      {
        "amount": 1,
        "appId": "",
        "bizNo": "",
        "extInfo": {},
        "gmtCreate": 1551676154000,
        "gmtModified": 1551676154000,
        "pmtDt": 1551676154000,
        "attachData": {},
        "sourceFrom": "",
        "goodsTitle": "",
        "id": "",
        "payChannel": "",
        "paymentStatus": "PAID"
      }
    ],
    "totalCount": 1
  }
}

note

Use totalCount to support pagination in your UI.

6. Query customer expire time

6.1 Endpoint

GET /customerServiceMgmt/{customerIdentity}.json

This endpoint returns a list of service records associated with a given customer, including each service’s expiration time.

6.2 Path parameters

Parameter	Type	Required	Description
`customerIdentity`	`string`	Required	Unique identifier for the customer. Used to look up associated services.

6.3 Successful response

{
  "msg": "success",
  "code": 0,
  "data": {
    "totalCount": 1,
    "customerServiceList": [
      {
        "expireTime": 1600560000000,
        "serviceName": "Demo的VIP服务",
        "serviceNo": "VIP"
      }
    ],
    "serverTime": 1600560000000
  }
}

7. Error codes and meanings

All API endpoints return a standardized error response format:

{
  "code": "error_code",
  "msg": "error_message"
}

For the full list of error codes and their meanings, see the Error reference.

note

Always handle errors based on the code field rather than relying on HTTP status codes, as all responses may return HTTP 200 even when the request failed.

1. Authentication and base URL​

1.1 Required headers​

Example (Java)​

Related docs​

1.2 Base URL​

2. Pay channel initialization​

2.1 Endpoint​

2.2 Purpose​

2.3 Required headers​

2.4 Successful response​

Key fields​

2.5 Error response​

3. Create order​

3.1 Endpoint​

3.2 Purpose​

3.3 Required headers​

3.4 Request parameters​

3.4.1 Using attachData effectively​

Recommended format​

Security and privacy​

Example (CreateOrder request body)​

Accepted values for sourceFrom​

3.5 Successful response examples​

WeChat Pay example​

Alipay example​

3.6 Error response​

4. Query single order​

4.1 Endpoint​

4.2 Request parameters​

4.3 Successful response​

Key fields​

5. Query order list​

5.1 Endpoint​

5.2 Request parameters​

5.3 Successful response​

6. Query customer expire time​

6.1 Endpoint​

6.2 Path parameters​

6.3 Successful response​

7. Error codes and meanings​

1. Authentication and base URL

1.1 Required headers

Example (Java)

Related docs

1.2 Base URL

2. Pay channel initialization

2.1 Endpoint

2.2 Purpose

2.3 Required headers

2.4 Successful response

Key fields

2.5 Error response

3. Create order

3.1 Endpoint

3.2 Purpose

3.3 Required headers

3.4 Request parameters

3.4.1 Using `attachData` effectively

Recommended format

Security and privacy

Example (CreateOrder request body)

Accepted values for `sourceFrom`

3.5 Successful response examples

WeChat Pay example

Alipay example

3.6 Error response

4. Query single order

4.1 Endpoint

4.2 Request parameters

4.3 Successful response

Key fields

5. Query order list

5.1 Endpoint

5.2 Request parameters

5.3 Successful response

6. Query customer expire time

6.1 Endpoint

6.2 Path parameters

6.3 Successful response

7. Error codes and meanings