Skip to main content

Capabilities and Limitations (Scope)

Clients sometimes expect a “payments system” to also manage products, users, discounts, promo codes, or subscriptions end-to-end. AppInChina Payments is intentionally not that type of platform.

This page clarifies what AppInChina Payments does, what it does not do, and where those responsibilities should live in your architecture.

If your main question is “what sales models can we use (without auto-renew) and who should manage what?”, see: Sales models in China (and recommended architecture).

What AppInChina Payments is​

AppInChina Payments provides a single SDK/API surface to initiate payments with WeChat Pay and Alipay, and to record and query transaction status.

It is designed to be:

  • A lightweight wrapper around the official payment providers (WeChat Pay / Alipay)
  • A consistent way to create orders, track them, and reconcile outcomes
  • A system that stores transaction records enriched with metadata you provide (for example goodsTitle, customerIdentity, attachData)

Your system (you own this)​

  • Product catalog: SKUs, pricing, currency rules, availability, inventory, subscription plans, etc.
  • Discounts & promotions: promo codes, coupons, pricing experiments, eligibility, stacked rules, etc.
  • User management: registration/login, account recovery, identity linking, admin tools, RBAC, etc.
  • Order model & fulfillment: internal order IDs, entitlements, content delivery, feature unlocks, subscription lifecycle logic.
  • Business reporting: revenue analytics, tax/invoice logic, CRM and customer support workflows.

AppInChina Payments (we own this)​

  • Payment initiation via SDK/API for WeChat Pay and Alipay
  • Transaction logging (order creation + recorded payment outcomes)
  • Order querying (single order and history)
  • Refund operations via the AppInChina Dashboard (the SDK does not provide refund APIs)
  • Optional purchase restore support via SMS authentication (for integrations that choose to use it)

What AppInChina Payments supports​

You can treat AppInChina Payments as the “payment rail” layer:

  • Create an order with the final payable amount and your identifiers
  • Send the user through WeChat Pay or Alipay
  • Verify the final status server-side (treat payment as successful only when paymentStatus == PAID)
  • Query history for a given user identity (customerIdentity)

Relevant docs:

What AppInChina Payments does not support (common misconceptions)​

AppInChina Payments does not provide:

  • Product management: creating products, managing SKUs, maintaining a price book, inventory, or catalog APIs
  • Discount engines: promo codes, coupons, rule-based discounts, user segmentation for pricing, or “apply code at checkout”
  • User management: account systems, user profiles, permissions, or admin management of users
  • Entitlement logic: granting coins, unlocking features, provisioning services, or managing your subscription lifecycle rules
  • Client-side proof of payment: return URLs, app callbacks, and “success screens” are not a secure confirmation (always verify server-side)

If you need a managed login/identity system, see the Login docs:

Since AppInChina Payments does not manage any of these concepts internally, here is how to represent each one through the fields the API does accept.

Users​

AppInChina Payments does not maintain user accounts. To link transactions to your users:

  • customerIdentity — pass your stable internal user ID (strongly recommended). This is the key used by /detail.json and /history.json to scope queries.
  • customerName — pass a human-readable identifier (username, phone, etc.) for reference in the Dashboard.

If you need a managed login/identity system for China, see Login solutions overview and Login → Payments integration (customer identity).

Products​

AppInChina Payments has no product catalog — every order is just an amount with metadata. To keep your products traceable:

  • goodsTitle — set it to a human-readable label (e.g. "Pro plan – 3 months"). This is what appears during checkout.
  • attachData — include your internal product/SKU ID so you can map the transaction back to your catalog at fulfillment time.
  • amount — always the final price your backend resolved for that product (in cents).

Your backend owns the catalog; AppInChina Payments just records what you tell it.

Entitlements​

A successful payment (paymentStatus == PAID) does not automatically grant anything to the user. AppInChina Payments records the transaction — your backend is responsible for fulfillment:

  • After verifying the order status via /detail.json or the SDK query, your backend decides what to unlock (features, content, subscription time, credits, etc.).
  • Use attachData to carry the context your fulfillment logic needs (e.g. productId, planId, tier) so you can map a paid transaction to the right entitlement without ambiguity.
  • If you support "restore purchases" flows, query /history.json by customerIdentity and re-derive entitlements from your own order records — AppInChina Payments provides the transaction data, not the entitlement state.

The key separation: payment completion is not fulfillment. Your system owns the link between "paid" and "granted".

General principle​

Your backend decides who is buying, what they're buying, and what to grant after payment succeeds. AppInChina Payments records the transaction with the identifiers you provide, but it does not interpret them as user accounts, products, or entitlements. See Using attachData effectively for metadata best practices.

Example: fixed-term subscription flow (where each piece lives)​

This walks through a "3-month Pro plan" purchase — from login to renewal — to show exactly which steps belong to your system and which ones involve AppInChina Payments.

For more sales models (one-time purchases, credit top-ups, bundles, etc.) see Sales models in China (and recommended architecture).

First purchase​

  1. User logs in through your login system (e.g. Authing, WeChat Login, or your own). Your backend returns a stable internal userId.
  2. App requests the product catalog from your backend. Your backend returns the available plans (e.g. Pro 1 month — ¥29, Pro 3 months — ¥69, Pro 1 year — ¥199) with their internal IDs and prices.
  3. User selects "Pro 3 months". The app sends the selection to your backend.
  4. Your backend creates an internal order:
    • Generates a unique order ID (this becomes bizNo).
    • Resolves the final price — applying any discount logic you own.
    • Records the order as PENDING in your database, linked to the userId and the plan.
  5. CreateOrder is called (via your backend calling POST /order.json, or via the Android SDK from the client) with:
    • amount: 6900 (¥69 in cents)
    • bizNo: your order ID
    • goodsTitle: "Pro plan – 3 months"
    • payChannel: WECHAT or ALIPAY
    • customerIdentity: userId
    • attachData: {"planId":"pro_3m","internalOrderId":"ORD_20260210_0042"}
  6. User completes payment inside WeChat Pay or Alipay.

Verification and fulfillment​

  1. Your backend verifies the payment by calling /detail.json with bizNo + customerIdentity.
    • Only proceed if paymentStatus == PAID. Any other status means the payment is not confirmed.
  2. Your backend fulfills the entitlement:
    • Reads attachData → knows this is pro_3m.
    • Sets subscription.expiresAt = now + 90 days for this user (or extends the existing expiry if already active).
    • Marks the internal order as FULFILLED.
  3. App refreshes entitlement state from your backend and unlocks Pro features.

AppInChina Payments recorded the transaction. Your backend decided what that transaction means (3 months of Pro access) and granted it.

Renewal (when the term expires)​

  1. Your backend detects the subscription is expiring (e.g. via a scheduled job, or when the app checks entitlement on launch).
  2. App prompts the user to renew. If the user agrees, repeat from step 3 — your backend creates a new internal order, calls CreateOrder with a new bizNo, and on confirmed payment extends expiresAt by another term.

There is no auto-renew happening on the AppInChina side. Each renewal is a new, explicit purchase.

Restore purchases (new device or reinstall)​

  1. User logs in on a new device. Your backend already has the entitlement record linked to their userId, so the app can restore access immediately.
  2. If you need to cross-check against payment history, query /history.json with customerIdentity and filter by paymentStatus == PAID. Use the attachData on each record to map transactions back to plans — then re-derive the current entitlement state in your backend.

AppInChina Payments provides the transaction data; your backend owns the entitlement state.