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
• ordered consumption for expiring and fallback numeric credit pools
• paid order recording for confirmed corporate bank transfers
• hosted login pages and multi-channel identity entry
• WeChat official account template-message binding and server-side sending
• SMS template notifications with verified phone binding or direct backend phone numbers
• server-side order, entitlement, and login verification APIs
• automatic recurring entitlement maintenance for subscription plans

These docs cover @youidian/sdk v3.6.3.

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.5.0, pricing backends should call getSubscriptionUpgradeOptions(userId, options) for platform-approved upgrade targets instead of comparing plan ranks. Use subscriptionIntent: "STANDARD" | "UPGRADE" when creating the order.

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 supports opening the hosted login page in an iframe modal. Pass displayMode: "popup" if you need the legacy full-popup flow.

Starting in SDK v3.4.0, LoginUI uses displayMode: "auto" by default: desktop browsers use the iframe modal, while mobile browsers, iPadOS, and WeChat embedded browsers redirect to the hosted login page. Call handleLoginCallbackIfPresent() on frontend initialization so redirect-based login can recover the final result.

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.

Starting in SDK v3.4.1, PaymentClient.consumeEntitlementPool(...) can consume numeric entitlements from ordered keys, and getEntitlementCreditBuckets(...) can list the active grant buckets that will be spent first. Use this for expiring subscription credits that should be consumed before perpetual credits. See Entitlement Credit Pools.

Starting in SDK v3.4.1, PaymentClient.createWechatMessageBinding(...) and sendMessage(...) support WeChat official account template message push. For unbound users, open the hosted binding page with MessageUI.openWechatBinding(...) first. See WeChat Message Push.

Starting in SDK v3.4.2, PaymentClient.getPhoneBinding(...) and updatePhoneNumber(...) let your backend query and change the verified phone number for a hosted login user. Use these with SMS notification templates when users must bind a phone number before receiving messages. See SMS Message Push.

Starting in SDK v3.4.4, PaymentClient.sendMessage(...) accepts direct SMS recipient fields such as phoneNumber, phoneCountryCode, and phoneE164. A successful direct-phone send can write the phone binding back to the identified hosted login user.

Brazilian Portuguese locale aliases

Starting in SDK v3.6.3, use either pt or pt-BR anywhere an SDK option accepts locale. Both values use the same Brazilian Portuguese copy, app channel-visibility rules, and BRL pricing. Hosted pages also accept /pt-BR/... URLs without changing the visible URL. If a product has no Portuguese price, the configured default price is returned.

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. Entitlement Credit Pools
7. Login Integration
8. Automatic Login Callback
9. Advanced Integration
10. Payment Channel Reference
11. WeChat Message Push
12. SMS Message Push
13. WeChat Mini Program Integration
14. 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