Broker Onboarding Overview

This guide is for Broker project teams integrating Longport Whale for the first time. It covers preparation, solution confirmation, environment setup, integration, acceptance, and go-live after commercial confirmation.

flowchart TD
    A[Onboarding overview] --> B[Core objects and business flows]
    B --> C[Integration options]
    C --> D{Choose a technical path}
    D -->|Ready-made UI| E[WhaleApp SDK]
    D -->|Implement securities UI| F[WhaleCore SDK + Trading API]
    D -->|Institution-level backend| G[Broker API]
    C --> H[User-system integration]
    H --> I{Account opening in scope?}
    I -->|Yes| J[User binding and account opening]
    I -->|No| K[Skip account-opening workstream]
    C --> L{App messages required?}
    L -->|Yes| M[Message-push integration]
    L -->|No| N[Skip message workstream]
    E --> O[Integration, UAT, and go-live]
    F --> O
    G --> O
    J --> O
    K --> O
    M --> O
    N --> O
    O --> P[Operations and support]

flowchart LR
    A[Project kickoff] --> B[Business and technical discovery]
    B --> C[Confirm solution]
    C --> D[Open test environment]
    D --> E[Configure and develop]
    E --> F[Integration and UAT]
    F --> G{Accepted?}
    G -- No --> E
    G -- Yes --> H[Prepare production]
    H --> I[Go-live cutover]
    I --> J[Hypercare]

Both parties name project owners and a stable communication mechanism, including these roles:

Kickoff should produce an implementation plan covering scope, owners, milestones, risks, and open decisions.

Before requesting an environment, confirm at least:

• Business scope: markets, products, account types, currencies, and whether opening, cash, trading, IPO, and other capabilities are included.
• Integration boundary: WhaleApp SDK, WhaleCore SDK + Trading API, or Broker API, and which party maintains the Customer user system.
• Account model: mappings among Broker’s user identifier, Whale user identifier, and brokerage-account number.
• Compliance flow: opening information, KYC, risk assessment, approval, and failure handling.
• Messages: Whale-managed or Broker-owned push, App identifiers, vendor channels, and distribution responsibility.
• Infrastructure: UAT and production outbound IPs, domain access, secret storage, and callback addresses.
• Delivery: configuration, initial data, integration cases, UAT criteria, release window, and rollback owner.

See Integration options for product selection.

Discovery should produce a solution-confirmation record stating:

• Whether Broker App uses WhaleApp SDK (iOS, Android, or WebTrade) or WhaleCore SDK + Trading API to implement the securities UI.
• Which Broker API capabilities Broker Server uses.
• Who manages Customer users and how open_id remains stable.
• How opening applications are submitted, queried, and shown after failure.
• Whether Whale sends through managed channels or forwards to Broker Server.
• Which capabilities are outside the current scope and how they will be handled later.

• UAT and production outbound-IP allowlists.
• Technical, business-acceptance, and production-incident contacts.
• User, account, and business-field mappings.
• Planned opening, cash, trading, and other scenarios and expected volume.
• UAT data and acceptance participants.

• Environment endpoints and connectivity requirements.
• Credentials for the approved scope and a secure delivery method.
• Confirmed business configuration, field constraints, and test accounts.
• API documentation, error rules, and integration-support channel.

• Broker records the UAT endpoint, purpose, and owner.
• DNS, TLS, proxy, outbound IP, and allowlist pass verification.
• Credentials arrived securely and are stored in Broker’s secret-management facility.
• Broker authenticates successfully with the simplest read-only endpoint.
• Test accounts, markets, currencies, and required initial data are available.
• UAT and production configuration, credentials, and data cannot mix.

Verify a minimum closed loop and expand incrementally:

1. Verify network, credentials, and the simplest read-only request.
2. Complete user linking and account opening and persist every business identifier.
3. Complete cash, trading, status-query, and other core scenarios.
4. Follow Message-push integration to test device delivery or Server-to-Server forwarding.
5. Test asynchronous work, retries, duplicate requests, and failure recovery.
6. Check permissions, rate limits, redacted logs, monitoring, and alerts.
7. Have the business team execute UAT and record acceptance.

See Integration testing, UAT, and go-live for the detailed process.

• Scenario, input, expected result, and actual result.
• Request time, environment, endpoint, redacted business identifier, and correlation ID.
• Intermediate and final asynchronous states.
• Issue owner, resolution, and regression result.
• UAT acceptor and final confirmation.

Before go-live, jointly confirm:

• Production domains, IP allowlists, and credentials are verified.
• Production configuration matches the accepted configuration and every difference is recorded.
• Critical business outcomes, error rate, latency, and asynchronous work are monitored.
• Release steps, observation signals, stop conditions, and rollback were rehearsed.
• Technical and business owners from both parties can respond during the release window.

After cutover, enter the agreed hypercare period and track production requests, business results, and remaining issues. Move to normal support after hypercare ends.