Youidian Unified Portal Docs

What this page solves: it defines the single recommended integration path for Youidian Unified Portal.
Who it is for: standard hosted integrations that want the fastest implementation path.
What you will get: one default route that an AI agent or developer can implement without making architecture choices.

What Youidian Unified Portal provides

Youidian Unified Portal hosts these capabilities:

• product, pricing, and payment channel configuration
• unified product-list retrieval with product entitlements
• hosted payment pages and order creation flow
• realtime product stock queries for limited inventory products
• custom amount balance or credit recharge for numeric entitlements
• paid order recording for confirmed corporate bank transfers
• hosted login pages and multi-channel identity entry
• server-side order, entitlement, and login verification APIs
• automatic recurring entitlement maintenance for subscription plans

These docs cover @youidian/sdk v3.3.10.

Single recommended path

The default documentation teaches one route only:

1. Install @youidian/sdk
2. Use PaymentUI from @youidian/sdk/client on the frontend
3. Use LoginUI from @youidian/sdk/client on the frontend
4. Use PaymentClient from @youidian/sdk/server on the backend
5. After payment, let your backend query the order, read entitlements, and grant business access
6. After login, let your backend verify loginToken and create the local user session

In the default path:

• payment usually starts by loading the product list, then uses productCode
• balance recharge products can expose metadata.customAmount for hosted or integrator-side amount input
• login uses loginToken
• your business does not create the order first
• user entitlements are hosted by the unified platform by default
• you do not need apiUrl, checkoutUrl, loginUrl, baseUrl, or allowedOrigin

Starting in SDK v3.1.0, integrators can also call getActiveSubscription(userId) on the backend when they want to decide whether a pricing page should show “already purchased”, “upgrade”, or “manage plan”. That decision belongs to the integrator backend, not the public hosted checkout page.

Starting in SDK v3.2.0, LoginUI automatically creates a same-origin login callback URL for OAuth redirects. Standard login integrations do not need to create a custom callback page.

Starting in SDK v3.2.2, login callbacks no longer send callbackUrl as a query parameter. The SDK passes callback context through hash/window.name, avoids popup.closed polling by default, and does not force the callback page to call window.close().

Starting in SDK v3.3.0, LoginUI opens the hosted login page in an iframe modal by default. Pass displayMode: "popup" if you need the legacy full-popup flow.

Starting in SDK v3.3.2, the root package also exports the server-side phone binding request and response types. Use PaymentClient.sendPhoneVerificationCode(...) and PaymentClient.bindPhoneNumber(...) when your backend lets a logged-in hosted user bind a phone number inside your own account settings flow.

Starting in SDK v3.3.10, PaymentClient.createOrder(...) accepts merchantPricing for backend-calculated transaction prices. Use it only in advanced flows where your backend owns coupon, membership, campaign, or enterprise pricing logic. If the final amount is 0, create the order with channel FREE and open the existing-order checkout.

If the customer has already paid through an offline corporate bank transfer and your finance or business system has confirmed the funds, use PaymentClient.createBankTransferOrder(...) to record a paid order. See Bank Transfer Orders for the full flow.

Starting in SDK v3.3.10, PaymentClient also exposes realtime stock queries for limited products. Query stock before you render a buy button, and treat OUT_OF_STOCK from order creation as a normal sold-out response. See Inventory-Limited Products for the full stock lifecycle and parameter guide.

Starting in SDK v3.3.10, hosted payment modals also send a best-effort cancellation request when the user cancels or closes a pending payment. For inventory-limited products, this releases the pending stock reservation sooner instead of waiting for the reservation timeout.

For special control requirements, private deployment, or custom domains, see Advanced Integration.

Recommended payment flow

Your backend
  -> getProducts(...)
  -> getProductStock(...) or getProductStocks(...)
  -> Your pricing page shows products, prices, entitlements, and stock
  -> Your frontend PaymentUI.openPayment({ appId, userId, productCode })
  -> Youidian Unified Portal hosted payment page
  -> User confirms product and pays
  -> Youidian Unified Portal creates and advances the order
  -> Frontend receives success callback with orderId
  -> Your backend queries order / entitlements
  -> Your system grants access, refreshes account state, or reads the updated balance

Recommended login flow

Your frontend
  -> LoginUI.openLogin({ appId })
  -> Youidian Unified Portal hosted login page
  -> User signs in
  -> Frontend receives loginToken
  -> Frontend posts loginToken to your backend
  -> Backend verifyLoginToken(loginToken)
  -> Your system matches or creates the local user and session

Reading order

1. Installation
2. Payment Integration
3. Custom Amount Balance Recharge
4. Bank Transfer Orders
5. Inventory-Limited Products
6. Login Integration
7. Automatic Login Callback
8. Advanced Integration
9. Payment Channel Reference
10. WeChat Mini Program Integration
11. Integration Checklist

Common mistakes to avoid

• Do not treat @youidian/sdk/login as the default entry
• Do not start the default payment path with a custom order creation flow
• Do not trust frontend login data without verifying loginToken
• Do not surface advanced override fields as standard hosted setup requirements