Skip to main content

Purchase History & Refund Workflows

To process refunds and handle customer support inquiries effectively, you must implement a Purchase History screen within your app.

This guide explains why this is a strict requirement, the minimum UI requirements you must meet, and how to build it using the AppInChina Payments API.

Why is a Purchase History UI required?​

AppInChina Payments is designed with strict data privacy principles. We do not store Personally Identifiable Information (PII) such as user phone numbers or email addresses in our payment records. We only store the opaque customerIdentity (your internal user ID) and the bizNo (your internal order ID).

When a user contacts your support team or our support team to request a refund, they will not know their hidden customerIdentity.

To locate the exact transaction in the AppInChina Dashboard, support agents must search using the bizNo (Order ID). Therefore, the user must have a way to view their past transactions and copy the bizNo to provide to the support agent.

Minimum UI Requirements​

To ensure a smooth customer support experience, your app's Purchase History screen must include the following for every successful transaction:

  1. The Order ID (bizNo): This is the most critical piece of information. It must be clearly visible.
  2. A "Copy" Button: Users are on mobile devices; do not force them to manually type out a long alphanumeric string. Provide a simple tap-to-copy mechanism next to the Order ID.
  3. Product Name (goodsTitle): What the user purchased (e.g., "Pro Plan - 3 Months").
  4. Purchase Date: The date and time the transaction was completed.
  5. Amount Paid: The final price the user paid.

Example UI Layout​

-----------------------------------
Order History
-----------------------------------
Pro Plan - 3 Months
Date: 2026-03-20 14:30
Amount: ¥69.00
Order ID: ORD_20260320_A1B2C3 [COPY]
-----------------------------------
Coins Top-Up (500)
Date: 2026-03-15 09:15
Amount: ¥18.00
Order ID: ORD_20260315_X9Y8Z7 [COPY]
-----------------------------------

How to build it​

You can build this UI using one of two approaches:

Because your backend is responsible for creating the bizNo and fulfilling the order, your database is the source of truth for the user's entitlements.

  • How: Your app queries your backend for the user's order history.
  • Why: This is the fastest and most robust method. It allows you to show orders that might be "Pending" or "Failed" in addition to "Paid" orders, providing better context to the user.

Approach 2: Use the AppInChina /history.json API​

If you prefer not to build a custom history endpoint on your backend, you can use the AppInChina Payments API to retrieve the user's transaction history.

  • How: Your backend calls the POST /history.json endpoint, passing the user's customerIdentity. Your backend then formats this data and sends it to your app to display.
  • Note: You should filter the results to only show transactions where paymentStatus == PAID.

The Customer Support Workflow​

Once you have implemented the Purchase History screen, the refund workflow looks like this:

  1. User experiences an issue and contacts customer support (either your team or AppInChina's team).
  2. Support agent requests the Order ID, instructing the user to go to Settings > Purchase History in the app.
  3. User copies the bizNo and sends it to the support agent.
  4. Support agent searches the AppInChina Dashboard using the exact bizNo.
  5. Support agent processes the refund directly from the dashboard.

By implementing this screen, you eliminate the need to handle sensitive PII during support requests and ensure that refunds are processed for the exact transaction the user is disputing.

How your app knows a subscription is still valid​

When the user opens the app again, the app should check the user's current entitlement state with your backend, not directly with AppInChina Payments.

Your backend should remain the source of truth for whether a user still has access. A typical app launch or resume flow is:

  1. User opens the app or returns to the foreground.
  2. App calls your backend with the logged-in user session.
  3. Your backend checks its own entitlement record, such as subscription status, expiresAt, and any refunded orders already reconciled.
  4. If your backend needs to confirm a payment or refund, it queries AppInChina using the relevant bizNo and customerIdentity.
  5. If the AppInChina order status is REFUND, your backend updates or revokes the related entitlement according to your refund policy.
  6. Backend returns the current entitlement state to the app, such as active: true or active: false.
  7. App unlocks or locks paid features based on your backend response.

The app does not need to refresh all AppInChina payment history every time it comes online. Instead, it should refresh the user's entitlement state from your backend. Your backend decides how often to reconcile with AppInChina based on your product rules, support workflow, and risk tolerance.