Login → Payments integration (customer identity)

This guide explains how to integrate your login system with AppInChina Payments so payments, order queries, purchase restoration, and subscriptions can be reliably associated with the correct user—regardless of which login solution you use (Authing, WeChat Login, custom backend, or a cloud IdP).

Key concept: customerIdentity

Most AppInChina Payments flows accept a customerIdentity field. Treat it as your stable internal user identifier.

Recommendation: use an internal userId that is:

• Stable (never changes)
• Unique per user
• Not user-editable
• Not derived from a device identifier

Avoid using raw PII (plain phone/email) as the identity when possible.

Responsibility split (who owns what)

The easiest way to avoid integration gaps is to be explicit about ownership:

Area	Your system (client app + backend)	AppInChina Payments	WeChat Pay / Alipay
User accounts	Create accounts, login UX, account recovery, fraud/abuse controls	Not provided	Not provided
Identity mapping	Map provider identities (Authing/WeChat/OIDC) → internal userId	Records customerIdentity you send	Issues provider identities (e.g., WeChat openid) within their ecosystem
Sessions/tokens	Issue and validate your sessions; keep user signed-in	Not provided	Not provided
Product catalog & pricing	Define SKUs, pricing, eligibility, discounts	Not provided	Not provided
Order / entitlement model	Create internal orders, grant entitlements after payment is verified	Stores transaction record + status; returns query results	Processes the actual payment
Payment UI	Decide when to show paywall/checkout; start the payment flow	Starts payment via SDK/API	Displays native payment UI and authorizes payment
Payment confirmation	Verify final status server-side before fulfillment	Provides authoritative transaction status via query endpoints	Is the underlying payment rail
Refunds	Your business policy + customer support; decide eligibility	Refund operations via Dashboard (per our product scope)	May be involved as the underlying processor

Where customerIdentity is used

Depending on your integration path (SDK vs API), customerIdentity is typically used for:

• Order creation metadata (linking a payment to the user)
• Order detail queries (used to prevent unauthorized order lookup)
• Order history queries
• Purchase restoration and subscription management

What customerIdentity should be (and should not be)

Recommended

• Your internal stable userId (database ID or UUID), returned by your backend after login

Not recommended

• Device identifiers
• Mutable identifiers (email/phone) unless you have a migration strategy
• External provider identifiers as your primary identity (WeChat openid/unionid, OIDC sub, etc.)
  • You can store them, but map them to your internal userId

What you must implement (login-solution agnostic)

No matter what login solution you choose, your product should implement:

• A stable internal user ID (userId)
• A mapping from the login provider identity to your internal userId
• Session/token handling so the user remains signed in and the correct identity is available during checkout
• Account recovery so users can regain access and restore purchases on a new device when applicable
• Account linking strategy if you support multiple login methods (e.g., WeChat + phone/email)

Implementation pattern (recommended)

1. User authenticates (Authing / WeChat / custom / OIDC).
2. Your backend resolves/creates an internal user record and returns your internal userId.
3. Your app stores a session token; whenever the user enters a payment flow, it fetches/uses the internal userId.
4. Your app/backend includes customerIdentity = userId in AppInChina Payments calls (create order / query / history).

“Who stores what?” (recommended minimal data model)

At minimum, your backend should store:

• User
  • userId (internal stable ID)
  • attributes (email/phone/display name as needed)
• External identities (one-to-many)
  • provider (authing / wechat / oidc / etc.)
  • providerUserId (e.g., Authing user ID, WeChat unionid, OIDC sub)
  • userId (your internal stable ID)
• Orders / entitlements
  • bizNo (your internal order ID)
  • userId (who is buying)
  • product/plan identifiers
  • fulfillment status

AppInChina Payments will store the transaction record keyed by the identifiers you provide (including bizNo and customerIdentity) and allow you to query status/history.

Provider-specific notes (how to map to internal userId)

Authing

• Store Authing’s user identifier in your database (as an external identity record).
• Map it to your internal userId.
• Use internal userId as customerIdentity.

WeChat Login

• WeChat identities (e.g., openid / unionid) are provider identifiers, not your internal ID.
• Store them as external identities and map to one internal userId.
• If you also support other login methods, implement account linking to avoid duplicate user accounts.

Custom backend (email/phone/password/OTP)

• Generate a stable internal userId at account creation time.
• If you use phone/email for login, treat them as attributes, not the primary key.

Cloud identity / OIDC (Cognito, Firebase, Auth0, Microsoft, etc.)

• Treat the IdP “subject” / provider user ID as an external identity.
• Map it to one internal userId.
• Use internal userId as customerIdentity.

Common pitfalls

• Using device ID as identity: breaks restoration on device change.
• Using mutable identifiers (email/phone) as the identity: changes can orphan history unless you migrate carefully.
• Using a provider identifier directly: complicates account linking (and can break if you later support multiple login methods).
• Not persisting identity across sessions: causes mismatched customerIdentity during queries/restoration.

Support / debugging checklist (what we’ll ask for)

When troubleshooting identity-related issues, have these ready:

• The bizNo you created
• The customerIdentity you sent for order creation
• The customerIdentity you are using for order query (must match)
• The payChannel and environment (test vs production)
• Timestamp + device/app version logs around CreateOrder / startPayment / query

Related docs

• Login solutions overview: /login/
• High-level flow: Understanding the IAP SDK/API Flow
• Payments API reference: Payments API Reference
• Android SDK guide: Payments SDK Integration Guide for Android
• Purchase restore & SMS authentication: Purchase Restore and SMS Authentication