@dropp.cc/payment-sdk 1.0.24 → 1.0.26

package/README.md

@@ -1,537 +1,2079 @@
-# Dropp Payment SDK for Web
+# Dropp Web Payment SDK — Developer Integration Guide
+
+## 1. Overview
+
+The **Dropp Web Payment SDK** enables a merchant's web application to integrate Dropp payment and wallet functionality without implementing the complete Dropp payment UI and wallet-management experience themselves.
+
+The SDK is framework-agnostic and can be integrated with:
+
+- React
+- Vue
+- Angular
+- Next.js
+- Vanilla JavaScript
+
+The SDK currently supports three payment models:
+
+1. **Standard Payment** — immediate, one-time payment.
+2. **Pre-Authorization Payment (PreAuth)** — temporarily reserves/authorizes funds before the final amount is known.
+3. **Recurring Payment** — creates a recurring authorization for subscription-style billing.
+
+In addition to payments, the SDK provides APIs for:
+
+- SDK initialization
+- Wallet/account status
+- Account/funding-source linking and unlinking
+- Dashboard access
+- Direct access to individual wallet-management pages
+- Payment-window management
+- SDK/environment information
+- Unified payment callbacks
+
+---
+
+# 2. Integration Flow
+
+A merchant should generally integrate the SDK in the following order:
+
+```text
+1. Prerequisites & Merchant Configuration
+                 ↓
+2. Install and Initialize SDK
+                 ↓
+3. Payment APIs
+   ├── Standard Payment
+   ├── PreAuth Payment + Backend Callback
+   └── Recurring Payment + Backend Callback
+                 ↓
+4. Account APIs
+   ├── Link Account / Funding Source
+   ├── Unlink Account / Funding Source
+   └── Status
+                 ↓
+5. Custom Pages
+   ├── Dashboard
+   └── Direct Module / Page Access
+                 ↓
+6. Handle Responses, Errors & Callbacks
+                 ↓
+7. Backend Verification & Production Readiness
+```
+
+The recommended implementation is to complete the prerequisites and initialization first, then integrate the required payment flow, followed by account-management and custom-page functionality.
+
+---
+
+# 3. Prerequisites
+
+Before integrating the SDK, the merchant must complete the required Dropp merchant configuration.
+
+## 3.1 Merchant Requirements
+
+The merchant should have:
+
+- An active Dropp Merchant Account.
+- Completed merchant KYC approval.
+- A Merchant ID issued by Dropp.
+- An API Key issued by Dropp.
+- An approved Package Name / Application Identifier / Domain registered in the Dropp Merchant Portal.
+
+## 3.2 Technical Requirements
+
+The integration requires:
+
+- Node.js 18+ for package-based integrations.
+- A modern web browser.
+- HTTPS for production deployments.
+
+---
+
+## 3.3 Register the Host Application
+
+Before initializing the SDK, register the host application in the Dropp Merchant Portal.
+
+1. Log in to the Dropp Merchant Portal.
+2. Navigate to **Profile**.
+3. Open **Embedded Application Integration**.
+4. Click the **Edit** icon.
+5. Configure:
+   - Platform — for example Web.
+   - Tag — optional where applicable.
+   - Package Name / Bundle Identifier / Domain.
+6. For a Web application, enter the domain without `https://` and without a path.
+
+Example:
+
+```text
+example.com
+```
+
+Do not configure:
+
+```text
+https://example.com
+https://example.com/payment
+```
+
+For local development, `localhost` or `127.0.0.1` can be registered. The host application must then be accessed using the configured domain/IP.
+
+Important: for Web SDK validation, the runtime host is derived from the active browser URL host. Ensure the exact host you open in browser (for example `localhost` vs `127.0.0.1`) is registered in the Merchant Portal.
+
+6. Save the application configuration.
+7. Generate an API Key.
+
+### API Key Important Notes
+
+The API key is displayed only once.
+
+Store it securely immediately after generation because it cannot be viewed again.
+
+An API key can be rotated or deleted. Once a key is rotated or deleted, the previous key becomes permanently invalid and cannot be used again.
+
+> **Security:** Never expose private signing keys or other backend secrets in frontend code.
+
+---
+
+# 4. Environment Configuration
+
+The SDK supports two environments.
 
-A secure, production-ready JavaScript SDK for integrating Dropp payments into web applications.
+## 4.1 Sandbox
 
-## Features
+Use Sandbox for:
 
-- 🔒 **Secure** - Origin validation, message authentication, session correlation
-- 🎯 **Framework-agnostic** - Works with React, Vue, Angular.
-- 📱 **Responsive** - Optimized for desktop and mobile browsers
-- ⚡ **Lightweight** - Minimal bundle size, no dependencies
-- 📦 **TypeScript** - Full TypeScript definitions included
+- Initial SDK integration.
+- Development.
+- Payment-flow testing.
+- Testing account linking.
+- Testing PreAuth and recurring flows.
 
+```js
+environment: 'sandbox'
+```
+
+## 4.2 Production
+
+Production is used for real customer payments.
+
+```js
+environment: 'production'
+```
+
+Do not move to production until the complete payment and backend-signing flows have been tested successfully.
+
+---
+
+## 4.4 Sandbox Wallet Configuration
+
+For Sandbox testing, the Dropp Wallet and merchant SDK must use the Sandbox environment.
+
+1. Open the Dropp Wallet mobile application.
+2. Recover the wallet account used for testing.
+3. Navigate to **Settings → Developer Options**.
+4. Enable **Switch to Test Mode**.
+5. Configure the SDK with the Sandbox Merchant ID and Sandbox API Key.
+6. Start the application/payment flow.
+7. The SDK may display a QR code for authentication.
+8. Scan the QR code using the Dropp Wallet configured for Sandbox.
+9. Enter the wallet passphrase when prompted.
+10. Continue testing after successful authentication.
+
+## 4.5 Wallet Persistence and Browser Storage Caveats
+
+Wallet-link persistence for Web SDK flows depends on hosted Dropp browser storage for the embedded experience.
+
+Important behavior to account for during testing and production rollout:
+
+1. Link state can be scoped to the top-level host origin. For example, `localhost`, `127.0.0.1`, and a tunnel URL are treated as different contexts.
+2. Browser privacy settings, third-party cookie restrictions, and storage partitioning can cause users to re-link more frequently.
+3. Opening the same app under different hostnames can appear like separate wallet-link sessions.
+
+Recommendations:
+
+1. Use one stable host/domain during test cycles.
+2. Keep host/domain registration in Merchant Portal aligned with the actual browser hostname used at runtime.
+3. Include relinking fallback UX and account-status checks using `Dropp.status()`.
+4. Validate behavior across your supported browser matrix with default privacy settings.
 
-## Installation
+---
 
-Install the SDK using npm:
+# 5. Install the SDK
+
+## 5.1 npm
 
 ```bash
 npm install @dropp.cc/payment-sdk
 ```
 
-## Initialization
-
-### `Dropp.init(config)`
+## 5.2 Yarn
 
-Initializes the SDK with the required configuration.
+```bash
+yarn add @dropp.cc/payment-sdk
+```
 
-**Parameters:**
+---
 
-- `config` (Object):
-  - `merchantId` (String) **Required**: Your Dropp merchant identifier, Will get from Dropp Merchant Portal after KYC.
-  - `apiKey` (String) **Required**: API key issued for your merchant,  Will get from Dropp Merchant Portal after KYC.
-  - `packageName` (String) **Required**: Your app/package name (for example, `app.dropp.cc`), will need to update in your account on the Dropp Merchant Portal.
-  - `environment` (String) **Required**: The environment to use. Options: `'production'`, `'qa'`, `'sandbox'`.
-  - `getServerAuthToken` (Function) **Optional**: Async callback that returns a short-lived server-issued token.
-  - `requireServerAuthToken` (Boolean) **Optional**: Require server token for payment initialization. Defaults to `true` in production.
+# 6. Initialize the SDK
 
+The SDK must be initialized before calling payment, account, dashboard, or custom-page APIs.
 
-### Example:
+```js
+import { Dropp } from '@dropp.cc/payment-sdk';
 
-```javascript
 Dropp.init({
   merchantId: 'YOUR_MERCHANT_ID',
   apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'production',
-  getServerAuthToken: async (context) => {
-    const response = await fetch('https://your-backend.com/dropp/auth-token', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(context)
-    });
-    const body = await response.json();
-    return body.authToken;
-  }
+  environment: 'sandbox'
 });
 ```
 
-## Payment
+## 6.1 Initialization Parameters
 
-### `Dropp.pay(options)`
+| Parameter | Required | Description |
+|---|---|---|
+| `merchantId` | Yes | Merchant account ID (for example `0.0.123456`) provided by Dropp. |
+| `apiKey` | Yes | API key generated for the registered host application. |
+| `environment` | Yes | SDK environment: `sandbox` or `production`. |
 
-Initiates a payment process.
+> The exact application identifier configured in the Merchant Portal must match the host application configuration expected by the SDK.
 
-**Parameters:**
+---
 
-- `options` (Object):
-  - `merchantAccount` (String) **Required**: The merchant's Hedera account ID (e.g., `'0.0.123456'`).
-  - `amount` (Number) **Required**: The payment amount.
-  - `currency` (String) **Required**: The currency code (e.g., `'USD'`, `'HBAR'`, `'USDC'`). For `paymentType: 'preauth'`, only `'USD'` is allowed.
-  - `itemName` (String) **Required**: The name of the item or service.
-  - `paymentType` (String) **Required**: The type of payment. Options: `'standard'`, `'preauth'`, `'recurring'`.
-  - `authHoldTimeInSeconds` (Number) **Required in Preauth Payments**: For preauth payments, the hold time in seconds.
-  - `callbackUrl` (String) **Required in Preauth & Recurring**: The server URL on which the PreAuth and Recurring requests will be send for signing.
-  - `recurringEndDate` (ISO datetime) **Optional in Recurring Payments**: The date on which the recurring authorization will expire. 
-  - `serverAuthToken` (String) **Optional**: A short-lived token issued by your backend for this payment.
+# 7. Payments
 
-### Example:
+The SDK exposes a single payment entry point:
 
-```javascript
-Dropp.pay({
-  merchantAccount: '0.0.123456',
-  amount: 100.00,
+```js
+Dropp.pay(options)
+```
+
+The `paymentType` determines which payment flow is started.
+
+Supported values:
+
+```text
+standard
+preauth
+recurring
+```
+
+The payment flow opens the Dropp-managed payment UI and returns a Promise containing the payment result.
+
+## 7.1 Single Active Flow Constraint
+
+The Web SDK allows only one active flow at a time (payment, hosted page, or status check).
+
+If a second call starts before the first finishes, SDK returns `ALREADY_OPEN`.
+
+Recommended host-app behavior:
+
+1. Disable actions that call Dropp APIs while a flow is active.
+2. Re-enable on success, failure, cancel, or close.
+3. In React (including StrictMode), deduplicate mount-time `Dropp.status()` calls.
+
+## 7.2 Unicode Input Note
+
+Current payload encoding in Web SDK versions that use browser `btoa` can fail for non-Latin1 characters.
+
+Until UTF-8-safe encoding is available in your deployed SDK version:
+
+1. Use ASCII-safe `itemName` and `description` values, or
+2. Normalize/sanitize these fields before calling `Dropp.pay(...)`.
+
+---
+
+# 8. Standard Payment
+
+## 8.1 Purpose
+
+A **Standard Payment** is a one-time payment where the customer pays for a product or service immediately.
+
+Use Standard Payment when:
+
+- The amount is known at checkout.
+- The customer should be charged once.
+- No future authorization is required.
+
+Typical examples:
+
+- Product purchase.
+- Parking payment.
+- One-time service payment.
+- Invoice payment.
+- Digital product purchase.
+
+## 8.2 Example
+
+```js
+const result = await Dropp.pay({
+  amount: 49.99,
   currency: 'USD',
-  itemName: 'Premium Subscription',
+  itemName: 'Premium Product',
   paymentType: 'standard',
-  callbackUrl: 'https://example.com/callback'
+  description: 'One-time product purchase',
+  invoiceId: 'ORDER-12345'
 });
 ```
 
-## Pages
+## 8.3 Standard Payment Parameters
 
-The Web SDK can also open Dropp-hosted pages inside the same modal container.
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `paymentType` | string | Yes | Must be `standard`. |
+| `amount` | number | Yes | Payment amount. |
+| `currency` | string | Yes | Currency code such as `USD`. |
+| `itemName` | string | Yes | Name of the purchased item/service. |
+| `description` | string | No | Payment description. |
+| `invoiceId` | string | No (recommended) | Merchant order/reference identifier. If omitted, SDK generates `INV-<timestamp>`. |
+| `acceptPaymentDelay` | boolean | No | Allows delayed payment processing. Default is false when not supplied. |
+| `noOffers` | boolean | No | Disables promotional offers when set to true. |
+| `isSkipCrypto` | boolean \| null | No | Controls whether the cryptocurrency payment option is skipped. |
 
-### `Dropp.dashboard(options)`
+## 8.4 When to Use
 
-Open the dashboard/home page.
+Use:
 
-Optional for this route:
+```text
+paymentType: 'standard'
+```
 
-- `modules` (`string[]`): Restrict sidebar modules shown in webview.
+when the transaction should represent a normal one-time payment.
 
-Supported section IDs:
+---
 
-- `funding`
-- `accounts`
-- `merchants`
-- `settings`
-- `support`
+# 9. Pre-Authorization Payment
 
-Supported item IDs:
+## 9.1 Purpose
 
-- `fundnow`
-- `linkbank`
-- `linkcard`
-- `redeemnow`
-- `fundcrypto`
-- `transferusdc`
-- `usdchistory`
-- `redeemcrypto`
-- `manageaccounts`
-- `transactions`
-- `merchantlist`
-- `favorites`
-- `offers`
-- `profile`
-- `pinchange`
-- `unlinkaccount`
-- `accountsettings`
-- `about`
+A **Pre-Authorization Payment** authorizes/reserves funds without immediately capturing the final amount.
 
-The SDK passes this as a comma-separated query param in the webview URL for `#/firsttimeflow`.
+Use PreAuth when the final amount may be determined later or when a temporary authorization is required.
 
-### `Dropp.open(moduleId, options)`
+Typical use cases:
 
-Open a specific supported firsttimeflow item page directly.
+- Hotels.
+- Vehicle rentals.
+- Security deposits.
+- Event reservations.
+- Any transaction where a maximum amount needs to be authorized before final capture.
 
-Supported item IDs:
+## 9.2 Important Difference from Standard Payment
 
-- `fundnow`
-- `linkbank`
-- `linkcard`
-- `redeemnow`
-- `fundcrypto`
-- `transferusdc`
-- `usdchistory`
-- `redeemcrypto`
-- `manageaccounts`
-- `transactions`
-- `merchantlist`
-- `favorites`
-- `offers`
-- `profile`
-- `pinchange`
-- `unlinkaccount`
-- `accountsettings`
-- `about`
+| Standard | PreAuth |
+|---|---|
+| Immediate one-time payment | Authorization/hold |
+| Final payment occurs during the flow | Final amount may be determined later |
+| No backend signing callback required by the documented standard flow | Merchant backend callback is required |
+| Suitable for known purchase amount | Suitable when funds need to be reserved |
 
-This opens the module route directly as `#/${moduleId}`.
+---
 
-### `Dropp.unlinkAccount(options)`
+## 9.3 Example
 
-Loads the account unlink page.
+```js
+const result = await Dropp.pay({
+  amount: 100.00,
+  currency: 'USD',
+  itemName: 'Hotel Reservation',
+  paymentType: 'preauth',
+  description: 'Hotel reservation authorization',
+  invoiceId: 'RESERVATION-12345',
+  authHoldTimeInSeconds: 3600,
+  callbackUrl: 'https://merchant.example.com/pre-auth-post-callback'
+});
+```
 
-### `Dropp.transactions(options)`
+## 9.4 PreAuth Parameters
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `paymentType` | string | Yes | Must be `preauth`. |
+| `amount` | number | Yes | Maximum amount that may be authorized. |
+| `currency` | string | Yes | Currency code. |
+| `itemName` | string | Yes | Authorization name. |
+| `description` | string | No | Authorization description. |
+| `invoiceId` | string | No (recommended) | Merchant order/reference identifier. If omitted, SDK generates `INV-<timestamp>`. |
+| `authHoldTimeInSeconds` | number | Yes | Duration for which the authorization remains valid. |
+| `callbackUrl` | string | Yes | Public HTTPS endpoint on the merchant backend used for the callback request/response contract. |
+
+---
+
+# 10. PreAuth Host Server Requirement
+
+PreAuth requires a merchant backend server.
+
+The backend must be:
+
+- Publicly reachable.
+- Accessible through HTTPS.
+- Configured with the Dropp Backend SDK.
+- Able to receive signing requests.
+- Able to sign the required transaction payload.
+- Able to return the signed response.
+
+The frontend must **not** contain the merchant's private signing key.
+
+## 10.1 PreAuth Callback Flow
+
+```text
+Host Application
+      |
+      | Dropp.pay({ paymentType: 'preauth', callbackUrl })
+      ↓
+Dropp Payment Flow
+      |
+      | Signing request
+      ↓
+Merchant Backend
+      |
+      | Validate request
+      | Sign transaction
+      | Return signed response
+      ↓
+Dropp Payment Flow
+      |
+      ↓
+PreAuth Result
+      |
+      ↓
+Host Application
+```
 
-Loads the transactions page.
+## 10.2 Callback URL
 
-### `Dropp.offers(options)`
+The `callbackUrl` must point to the merchant backend application where the Dropp Backend SDK is integrated.
 
-Loads the offers page.
+Example:
 
-**Parameters:**
+```text
+https://merchant.example.com/pre-auth-post-callback
+```
 
-- `options` (Object) Optional:
-  - `onClose` (Function) **Optional**: Callback invoked when the modal is closed.
+A sample merchant backend application is available from the integration material:
 
-### Hosted Page Example:
+```text
+https://drive.google.com/drive/u/1/folders/1pWrBFQwnznhpRFPnsU_5qiy0TRp5dGUr
+```
 
-```javascript
-await Dropp.dashboard({
-  onClose: () => {
-    console.log('Dashboard modal closed');
-  },
-  modules: ['funding', 'accounts', 'merchants', 'settings', 'support']
-});
+### Running the Sample Backend
 
-await Dropp.unlinkAccount();
-await Dropp.transactions();
-await Dropp.offers();
+1. Download and extract the sample project.
+2. Update `.env` with the Merchant ID and Signing Key.
+3. Start the backend application locally.
+4. Expose the local server through ngrok or deploy it to a public HTTPS server.
+5. Use the public callback URL in `Dropp.pay()`.
 
-await Dropp.dashboard({
-  modules: ['funding', 'profile', 'about']
-});
+Example:
 
-await Dropp.open('linkbank');
-await Dropp.open('profile');
+```text
+https://<your-ngrok-url>/pre-auth-post-callback
 ```
 
-### SDK Instance Example:
+> The callback endpoint must be publicly accessible over HTTPS.
 
-```javascript
-const { sdk } = await Dropp.init({
-  merchantId: 'YOUR_MERCHANT_ID',
-  apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'production'
-});
+---
+
+# 11. Recurring Payment
+
+## 11.1 Purpose
+
+A **Recurring Payment** creates a recurring authorization for subscription or periodic billing.
+
+Use recurring payments when a merchant needs to charge a customer repeatedly according to a defined schedule.
+
+Typical use cases:
+
+- SaaS subscriptions.
+- Memberships.
+- Streaming services.
+- Monthly plans.
+- Periodic service billing.
 
-await sdk.dashboard();
-await sdk.dashboard({
-  modules: ['funding', 'accounts', 'merchants', 'settings', 'support']
+## 11.2 Example
+
+```js
+const result = await Dropp.pay({
+  amount: 9.99,
+  currency: 'USD',
+  itemName: 'Monthly Subscription',
+  paymentType: 'recurring',
+  description: 'Monthly subscription',
+  invoiceId: 'SUBSCRIPTION-12345',
+  callbackUrl: 'https://merchant.example.com/rps-callback',
+  recurringEndDate: new Date(
+    Date.now() + 365 * 24 * 60 * 60 * 1000
+  ).toISOString()
 });
-await sdk.open('fundnow');
-await sdk.open('transactions');
-await sdk.unlinkAccount();
-await sdk.transactions();
-await sdk.offers();
 ```
 
-## Account Status
+## 11.3 Recurring Parameters
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `paymentType` | string | Yes | Must be `recurring`. |
+| `amount` | number \| null | Conditional | Maximum or fixed recurring charge amount depending on the recurring configuration. |
+| `currency` | string | Yes | Currency code. |
+| `frequency` | RecurringInterval \| null | Conditional | Recurring interval. When supplied, amount is treated as a fixed amount; otherwise it represents the maximum amount according to the documented behavior. |
+| `itemName` | string | Yes | Subscription name. |
+| `description` | string | No | Payment description. |
+| `invoiceId` | string | No (recommended) | Merchant order/reference identifier. If omitted, SDK generates `INV-<timestamp>`. |
+| `recurringEndDate` | string | Yes | Expiry date in ISO-8601 format. |
+| `callbackUrl` | string | Yes | Public HTTPS backend callback endpoint. |
+
+## 11.4 Supported Frequencies
+
+| Frequency | Meaning |
+|---|---|
+| `HALF_HOURLY` | Every 30 minutes |
+| `HOURLY` | Every hour |
+| `DAILY` | Every day |
+| `WEEKLY` | Every week |
+| `MONTHLY` | Every month |
+| `YEARLY` | Every year |
+| `NONE` | No recurring interval; used for the documented maximum-amount behavior |
+
+---
+
+# 12. Recurring Payment Host Server Requirement
+
+Recurring payments require a merchant backend callback endpoint.
+
+The backend is responsible for receiving recurring authorization requests and signing the required payload using the Dropp Backend SDK.
+
+## 12.1 Recurring Callback Flow
+
+```text
+Host Application
+      |
+      | Create recurring authorization
+      ↓
+Dropp Payment Flow
+      |
+      | Signing request
+      ↓
+Merchant Backend
+      |
+      | Validate request
+      | Sign authorization
+      | Return signed response
+      ↓
+Dropp
+      |
+      ↓
+Recurring Authorization Result
+```
+
+## 12.2 Callback URL
+
+Example:
+
+```text
+https://merchant.example.com/rps-callback
+```
+
+The callback URL must point to the merchant backend application where the Dropp Backend SDK is integrated.
+
+Sample backend:
+
+```text
+https://drive.google.com/drive/u/1/folders/1pWrBFQwnznhpRFPnsU_5qiy0TRp5dGUr
+```
+
+For local testing:
+
+```text
+https://<your-ngrok-url>/rps-callback
+```
+
+The endpoint must be publicly accessible over HTTPS.
 
-Use `Dropp.status()` to fetch account linkage status.
+## 12.3 Callback Transport and Envelope (Important)
 
-### `Dropp.status()`
+For current hosted flows, callback transport differs by payment type:
 
-Returns:
+| Payment Type | Request Transport to `callbackUrl` | Main Payload Carrier |
+|---|---|---|
+| `recurring` | Browser `GET` | `RecurringData` query parameter |
+| `preauth` | Browser `POST` | JSON request body |
 
-```javascript
+The signed envelope should be handled as opaque and forwarded server-side:
+
+```json
 {
-  type: 'ACCOUNT_STATUS',
-  data: {
-    linked: true,
-    method: 'keypair'
+  "data": "<base64 payload>",
+  "signatures": {
+    "payer": "<hex signature>"
   }
 }
 ```
 
-### Example:
+Do not approve only from browser callback receipt. The merchant backend must first submit the payer-signed envelope to the authoritative Dropp backend path for the payment type, validate success, persist returned authorization/token metadata, then respond to hosted flow.
 
-```javascript
-const status = await Dropp.status();
-console.log('Account status:', status);
+## 12.4 Trust Boundary Requirement
+
+The callback request originates via the payer browser. Treat it as untrusted transport until the backend completes authoritative validation/forwarding.
+
+Minimum requirement:
+
+1. Receive callback on merchant backend.
+2. Validate request shape and merchant context.
+3. Forward payer-signed envelope to authoritative Dropp backend API for that flow.
+4. Approve hosted callback response only after authoritative success.
+5. Persist returned token/reference details needed for future preauth/recurring lifecycle operations.
+
+---
+
+# 13. Server Authentication
+
+Server Authentication protects payment requests from client-side tampering.
+
+The signing process should remain on the merchant backend.
+
+The general model is:
+
+```text
+Frontend
+  |
+  | Payment request
+  ↓
+Dropp
+  |
+  | Request server-side authorization/signing
+  ↓
+Merchant Backend
+  |
+  | Private signing key
+  | Sign payload
+  ↓
+Dropp
+  |
+  | Validate signature
+  ↓
+Payment continues
 ```
 
-### SDK Instance Example:
+## Security Rule
 
-```javascript
-const { sdk } = await Dropp.init({
-  merchantId: 'YOUR_MERCHANT_ID',
-  apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'production'
-});
+Never put a private signing key, signing secret, or equivalent backend credential in frontend JavaScript.
 
-const status = await sdk.status();
-console.log(status);
+The merchant backend should:
+
+1. Receive the signing request.
+2. Validate the request.
+3. Sign the required payload.
+4. Return the signed response.
+
+---
+
+# 14. Payment Response Handling
+
+`Dropp.pay()` returns a Promise.
+
+Always handle both:
+
+- A returned unsuccessful result.
+- A rejected Promise/error.
+
+```js
+try {
+  const result = await Dropp.pay(paymentOptions);
+
+  if (result && result.success === true) {
+    // Update application/order state
+  } else {
+    // Handle unsuccessful payment
+  }
+} catch (error) {
+  console.error('Payment error', error);
+}
 ```
 
-## Environments
+The merchant should verify the payment on the backend before fulfilling an order.
+
+Recommended flow:
+
+```text
+Customer initiates payment
+        ↓
+Dropp payment window opens
+        ↓
+Customer completes payment
+        ↓
+SDK returns payment response
+        ↓
+Merchant backend verifies payment
+        ↓
+Order/subscription is updated
+        ↓
+Merchant fulfills the order
+```
 
-The SDK supports the following environments:
+---
 
-- `'production'`: For live transactions.
-- `'qa'`: For quality assurance testing.
-- `'sandbox'`: For development and testing.
+# 15. Account APIs
 
-Ensure you use the appropriate environment for your use case.
+Account APIs are used when the host application needs to give the user access to their Dropp wallet/funding-source management without building those screens itself.
 
+The account-management area covers:
 
-```javascript
-import '@dropp/payment-sdk';
+- Linking a dropp account.
+- Unlinking a linked dropp account.
+- Checking whether an account is linked.
 
-Dropp.init({
-  merchantId: 'YOUR_MERCHANT_ID',
-  apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'sandbox' // For testing payments (testnet)
-});
+---
 
-Dropp.init({
-  merchantId: 'YOUR_MERCHANT_ID',
-  apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'qa' // For QA
-});
+# 16. Link Account
 
-Dropp.init({
-  merchantId: 'YOUR_MERCHANT_ID',
-  apiKey: 'YOUR_API_KEY',
-  packageName: 'com.example.webapp',
-  environment: 'production' // For live payments (mainnet)
-});
+## 16.1 Purpose
+
+The SDK does not expose a separate `Dropp.linkAccount()` method.
+
+To allow a user to link an account, the host application should open the **Dropp Dashboard**. The Dashboard provides the Dropp-managed account and experience where the user can complete the required linking flow.
+
+Use:
+
+```js
+Dropp.dashboard();
 ```
 
-## Payment Examples
+The host application should not implement a separate account-linking UI when the intention is to use the Dropp-managed experience.
 
-### Standard Payment
+## 16.2 When to Use
 
-```javascript
-Dropp.pay({
-  merchantAccount: '0.0.123456',
-  amount: 49.99,
-  currency: 'USD',
-  itemName: 'Premium Plan',
-  description: 'One-time purchase',
-  invoiceId: 'INV-2024-001'
-});
+Use the Dashboard for account linking when:
+
+- The user needs to connect an account.
+- The host application wants to provide the complete Dropp-managed wallet experience.
+- The user may need to perform other wallet actions in addition to linking.
+- The host application does not need to recreate Dropp's account-management UI.
+
+Example:
+
+```text
+Merchant Application
+        ↓
+"Link Account" / "Manage Wallet"
+        ↓
+Dropp.dashboard()
+        ↓
+Dropp-managed Dashboard
+        ↓
+User completes account-linking flow
+        ↓
+Host application can check the result/state with Dropp.status()
 ```
 
-### Pre-Authorization Payment
+## 16.3 Recommended Account-Linking Flow
 
-```javascript
-Dropp.pay({
-  merchantAccount: '0.0.123456',
-  amount: 100.00,
-  currency: 'USD',
-  itemName: 'Hotel Reservation',
-  description: 'Authorization hold for booking',
-  invoiceId: 'PREAUTH-001',
-  paymentType: 'preauth',
-  authHoldTimeInSeconds: 3600,  // 1 hour hold
-  callbackUrl: 'https://your-server.com/payment-callback'
-});
+A host application can first check the account state and then open the Dashboard when linking is required:
+
+```js
+const status = await Dropp.status();
+
+if (!status?.data?.linked) {
+  Dropp.dashboard();
+}
 ```
 
-### Recurring Payment
+This keeps the account-linking experience inside the Dropp-managed UI while allowing the host application to control when the Dashboard should be presented.
 
-```javascript
-Dropp.pay({
-  merchantAccount: '0.0.123456',
-  amount: 9.99,
-  currency: 'USD',
-  itemName: 'Monthly Subscription',
-  description: 'Recurring monthly payment',
-  paymentType: 'recurring',
-  frequency: 'monthly', // Frequency of the recurring payment
-  recurringEndDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(), // (optional) the date onwhich the recurring authentication will end.
-  callbackUrl: 'https://your-server.com/recurring-callback'
-});
+---
+
+# 17. Unlink Account
+
+## 17.1 Purpose
+
+`Dropp.unlinkAccount(options)` opens the unlink-account page.
+
+It is used to allow the user to safely remove a linked funding source from their Dropp wallet.
+
+```js
+Dropp.unlinkAccount(options);
 ```
-### React Integration
 
-```jsx
-import { useEffect, useState } from 'react';
-import { Dropp } from '@dropp/payment-sdk';
+## 17.2 When to Use
 
-function CheckoutButton() {
-  const [isProcessing, setIsProcessing] = useState(false);
+Use the unlink flow when:
 
-  useEffect(() => {
-    Dropp.init({
-      merchantId: 'YOUR_MERCHANT_ID',
-      apiKey: 'YOUR_API_KEY',
-      packageName: 'com.example.webapp',
-      environment: 'production'
-    });
-  }, []);
+- The user wants to remove a bank account.
+- The user wants to remove a card/funding source.
+- The host application provides an account-management or settings experience.
+- The merchant wants users to manage linked funding sources through Dropp's UI.
 
-  const handlePayment = async () => {
-    setIsProcessing(true);
+The SDK manages the unlink UI instead of requiring the host application to recreate the Dropp account-management screen.
 
-    try {
-      const result = await Dropp.pay({
-        merchantAccount: '0.0.123456',
-        amount: 99.99,
-        currency: 'USD',
-        itemName: 'Product Purchase',
-        paymentType: 'standard'
-      });
+---
 
-      if (result.status === 'success') {
-        alert('Payment successful!');
-      }
-    } catch (error) {
-      console.error('Payment error:', error);
-    } finally {
-      setIsProcessing(false);
-    }
-  };
+# 18. Account Status API
 
-  return (
-    <button onClick={handlePayment} disabled={isProcessing}>
-      {isProcessing ? 'Processing...' : 'Pay Now'}
-    </button>
-  );
+## 18.1 `Dropp.status()`
+
+The Status API allows the host application to determine the current linked-account state.
+
+```js
+const status = await Dropp.status();
+
+console.log(status);
+```
+
+The documented response format is:
+
+```js
+{
+  type: 'ACCOUNT_STATUS',
+  data: {
+    linked: true,
+    method: 'keypair'
+  }
 }
 ```
 
+## 18.2 Purpose
 
-### Vanilla JavaScript Integration
+The status API is useful when the host application needs to know whether the user already has a linked Dropp wallet/account before deciding what UI or action to show.
 
-Use this when you are not using React/Vue/Angular.
+For example:
 
-```html
-<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Dropp Vanilla JS Example</title>
-  </head>
-  <body>
-    <button id="payStandard">Pay Standard</button>
-    <button id="payPreauth">Pay Preauth</button>
-    <button id="payRecurring">Pay Recurring</button>
-
-    <script src="https://unpkg.com/@dropp/payment-sdk/dist/dropp-payment-sdk.js"></script>
-    <script>
-      const { Dropp } = window.DroppPaymentSDK;
-
-      Dropp.init({
-        merchantId: 'YOUR_MERCHANT_ID',
-        apiKey: 'YOUR_API_KEY',
-        packageName: 'app.dropp.cc',
-        environment: 'production'
-      });
+```text
+Application starts
+       ↓
+Dropp.status()
+       ↓
+Is account linked?
+   /          \
+ Yes          No
+  ↓            ↓
+Show wallet   Show link/authentication
+actions       flow
+```
 
-      document.getElementById('payStandard').addEventListener('click', async () => {
-        await Dropp.pay({
-          merchantAccount: '0.0.123456',
-          amount: 49.99,
-          currency: 'USD',
-          itemName: 'One-time Purchase',
-          paymentType: 'standard'
-        });
-      });
+## 18.3 Example
 
-      document.getElementById('payPreauth').addEventListener('click', async () => {
-        await Dropp.pay({
-          merchantAccount: '0.0.123456',
-          amount: 100.00,
-          currency: 'USD',
-          itemName: 'Hotel Reservation',
-          paymentType: 'preauth',
-          authHoldTimeInSeconds: 3600,
-          callbackUrl: 'https://your-server.com/payment-callback'
-        });
-      });
+```js
+const status = await Dropp.status();
 
-      document.getElementById('payRecurring').addEventListener('click', async () => {
-        await Dropp.pay({
-          merchantAccount: '0.0.123456',
-          amount: 9.99,
-          currency: 'USD',
-          itemName: 'Monthly Subscription',
-          paymentType: 'recurring',
-          frequency: 'monthly',
-          recurringEndDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
-          callbackUrl: 'https://your-server.com/recurring-callback'
-        });
-      });
-    </script>
-  </body>
-</html>
+if (status?.data?.linked) {
+  console.log('Dropp account is linked');
+} else {
+  console.log('Dropp account is not linked');
+}
 ```
 
-## Security
+The documented implementation performs the status check through a hidden iframe.
+
+## 18.4 Failure and Timeout Behavior
+
+`Dropp.status()` may reject instead of returning a status object.
+
+Common cases:
+
+1. Another SDK flow is active (`ALREADY_OPEN`).
+2. Status iframe initialization timed out (`INIT_TIMEOUT`).
+3. Status flow closed before response (`UNKNOWN_ERROR` depending on close path).
+
+Recommended handling:
+
+```js
+try {
+  const status = await Dropp.status();
+  const isLinked = status?.data?.linked === true;
+  console.log('linked?', isLinked);
+} catch (error) {
+  console.error('status failed', {
+    code: error?.code,
+    message: error?.message,
+    details: error?.details
+  });
+}
+```
+
+---
+
+# 19. Link vs Unlink vs Status
+
+| API / Flow | Purpose | Typical Use |
+|---|---|---|
+| `Dropp.dashboard()` | Open the Dropp-managed account/wallet experience | User needs to link an account or manage wallet functionality |
+| `Dropp.unlinkAccount(options)` | Open unlink-account UI | User wants to remove a funding source |
+| `Dropp.status()` | Check linked-account status | Host needs to determine current account state |
 
-The SDK implements multiple security layers:
+A typical host application can use them together:
 
-✅ **Origin Validation** - Strict validation of postMessage origins
-✅ **Session Correlation** - Each session has a unique ID to prevent replay attacks
-✅ **Message Authentication** - All messages are validated for structure and content
-✅ **Iframe Sandboxing** - Payment app runs in a sandboxed iframe
-✅ **No Sensitive Data** - SDK never handles sensitive payment data directly
-✅ **Secure Communication** - All data transmission uses HTTPS
+```js
+const status = await Dropp.status();
+
+if (!status?.data?.linked) {
+  await Dropp.open('linkbank');
+}
+```
 
-### Security Best Practices
+---
 
-1. **Never expose secrets in frontend code**
-2. **Use server-side callbacks** for payment verification
-3. **Validate payments on your backend** using the `callbackUrl`
-4. **Use invoice IDs** to track and deduplicate payments
-5. **Implement proper error handling**
+# 20. Custom Pages and Modules
 
-## Browser Support
+The SDK allows the host application to open Dropp-managed pages directly.
+
+This is useful when the merchant wants to provide access to specific wallet functionality while keeping the Dropp UI/UX.
+
+There are two main APIs:
+
+```js
+Dropp.dashboard(options);
+```
+
+and:
+
+```js
+Dropp.open(moduleId, options);
+```
+
+### Hosted Page Options (SDK Supported)
+
+Hosted page APIs support an options object used for lifecycle callbacks and page customization.
+
+| Option | Type | Used By | Description |
+|---|---|---|---|
+| `onClose` | function | `dashboard`, `open`, `unlinkAccount`, `transactions`, `offers` | Called when modal closes. |
+| `onCancel` | function | Hosted flows and payment flows | Called on cancellation/user close paths. |
+| `onFailed` | function | Hosted flows | Called when hosted flow reports a general failure. |
+| `onPageFailed` | function | Hosted flows | Called when a hosted page-level failure event is received. |
+| `onAccountChanged` | function | Hosted flows | Called for account-link state changes coming from hosted page events. |
+| `modules` | string[] | `dashboard` | Optional first-time-flow modules to display in sidebar. |
+
+Example:
+
+```js
+Dropp.dashboard({
+  modules: ['funding', 'profile', 'support'],
+  onAccountChanged: payload => console.log('account changed', payload),
+  onPageFailed: err => console.error('dashboard page failed', err),
+  onClose: () => console.log('dashboard closed')
+});
+```
+
+---
+
+# 21. Dashboard
+
+## `Dropp.dashboard(options)`
+
+### Purpose
+
+Opens the complete Dropp dashboard.
+
+The dashboard is intended to be the central wallet-management experience where users can access the sections and pages enabled by the host application.
+
+Use the dashboard when:
+
+- The host wants to give the user broad access to Dropp wallet features.
+- A dedicated wallet-management screen is not required in the host application.
+- Multiple Dropp modules need to be exposed together.
+
+## Example
+
+```js
+Dropp.dashboard({
+  modules: [
+    'funding',
+    'accounts',
+    'merchants',
+    'settings',
+    'support'
+  ]
+});
+```
+
+A smaller dashboard can be configured:
+
+```js
+Dropp.dashboard({
+  modules: [
+    'funding',
+    'profile',
+    'about'
+  ]
+});
+```
+
+`modules` is an optional list of section/item IDs that determines what is displayed in the sidebar.
+
+---
+
+# 22. Direct Page Access
+
+## `Dropp.open(moduleId, options)`
+
+### Purpose
+
+Opens a specific Dropp module/page directly instead of opening the full dashboard.
+
+This is useful for:
+
+- Deep linking.
+- Providing a direct "Link Bank" action.
+- Providing a direct "Transactions" action.
+- Opening profile/settings functionality.
+- Sending the user directly to a specific Dropp task.
+
+Example:
+
+```js
+Dropp.open('linkbank');
+Dropp.open('profile');
+Dropp.open('transactions');
+```
+
+---
+
+# 23. Supported Section IDs
+
+The documented section IDs are:
+
+| Section ID | Purpose |
+|---|---|
+| `funding` | Funding-related wallet functionality. |
+| `accounts` | Account/funding-source management functionality. |
+| `merchants` | Merchant-related functionality. |
+| `settings` | User and wallet settings. |
+| `support` | Support-related functionality. |
+
+These IDs can be used with `Dropp.dashboard()` and the supported navigation model.
+
+---
+
+# 24. Supported Item/Page IDs
+
+The following item IDs are documented.
+
+| Item ID | Page Purpose |
+|---|---|
+| `fundnow` | Opens the funding-now experience so the user can fund the wallet. |
+| `linkbank` | Opens the bank-account linking flow. |
+| `linkcard` | Opens the card-linking flow. |
+| `redeemnow` | Opens the redeem-now experience. |
+| `fundcrypto` | Opens the cryptocurrency funding experience. |
+| `transferusdc` | Opens the USDC transfer experience. |
+| `usdchistory` | Opens USD transaction/history functionality. |
+| `redeemcrypto` | Opens the cryptocurrency redemption experience. |
+| `manageaccounts` | Opens account-management functionality. |
+| `transactions` | Opens transaction history. |
+| `merchantlist` | Opens the merchant list. |
+| `favorites` | Opens the user's favorite merchants/items where supported. |
+| `offers` | Opens available offers and promotions. |
+| `profile` | Opens the user's profile. |
+| `pinchange` | Opens the PIN-change functionality. |
+| `aboutus` | Opens the About Us page. |
+
+> The page descriptions above describe the purpose implied by the documented module names and the existing SDK documentation. Any additional page-specific request parameters or callbacks should be documented from the SDK implementation if they are supported.
+
+---
+
+# 25. Custom Page Usage Examples
+
+## Open Funding
+
+```js
+Dropp.open('fundnow');
+```
+
+Use when the host application wants the user to directly access wallet funding.
+
+## Link Bank
+
+```js
+Dropp.open('linkbank');
+```
+
+Use when the user needs to connect a bank account.
+
+## Link Card
+
+```js
+Dropp.open('linkcard');
+```
+
+Use when the user needs to connect a card.
+
+## Transactions
+
+```js
+Dropp.open('transactions');
+```
+
+Use when the host application wants to show the user's transaction history.
+
+## Profile
+
+```js
+Dropp.open('profile');
+```
+
+Use when the host application wants to send the user directly to profile management.
+
+## Offers
+
+```js
+Dropp.open('offers');
+```
+
+Use when the merchant wants the user to view available promotions and offers.
+
+## About
+
+```js
+Dropp.open('aboutus');
+```
+
+Use to open the Dropp About Us page.
+
+---
+
+# 26. Choosing Between Dashboard and `open()`
+
+Use `Dropp.dashboard()` when:
+
+```text
+The user needs access to multiple wallet functions.
+```
+
+Use `Dropp.open()` when:
+
+```text
+The host application knows exactly which task the user needs to perform.
+```
+
+Example:
+
+```text
+Host App
+   |
+   +-- "Wallet" button
+   |       ↓
+   |   Dropp.dashboard()
+   |
+   +-- "Link Bank" button
+   |       ↓
+   |   Dropp.open('linkbank')
+   |
+   +-- "Transactions" button
+           ↓
+       Dropp.open('transactions')
+```
+
+---
+
+# 27. Utility APIs
+
+The SDK also exposes utility functions.
+
+## 27.1 `getInstance()`
+
+Returns the current initialized SDK instance.
+
+```js
+const instance = Dropp.getInstance();
+```
+
+The documented return type is:
+
+```text
+DroppPaymentSDK | null
+```
+
+It returns `null` when an initialized SDK instance is not available.
+
+Use this primarily for SDK state/diagnostic purposes rather than as the primary integration API.
+
+---
+
+# 28. Unified Callbacks
+
+The SDK uses callbacks to notify the host application about payment-flow state.
+
+| Callback | When It Is Triggered |
+|---|---|
+| `onSuccess` | Payment or authorization completed successfully. |
+| `onFailure` | Transaction failed, for example due to insufficient funds or technical errors. |
+| `onCancel` | User explicitly closed the payment window without completing the payment. |
+
+A host application should use these callbacks, where configured/supported by the SDK integration, to update its own UI and application state.
+
+---
+
+# 29. Payment Response — Standard
+
+A Standard Payment returns a response similar to:
+
+```js
+{
+  success: true,
+  paymentType: 'PAYMENT',
+  title: 'Payment Successful!',
+  message: 'Payment successful!',
+  transactionId: 'ABCS-38947835',
+  invoiceId: 'ABC-29388474',
+  reference: 'ORDER-12345',
+  merchantAccount: '0.0.100010',
+  amount: 50,
+  currency: 'USD',
+  paidAmount: 50,
+  paidCurrency: 'USD',
+  itemName: 'PARKING BILL',
+  description: 'Parking Meter Bill for 30min',
+  paymentRef: 'response.data.paymentRef',
+  iso20022Response: '<?xml version="1.0"...',
+  sessionDuration: 9425
+}
+```
+
+Important response fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | boolean | Whether the payment succeeded. |
+| `paymentType` | string | `PAYMENT` for Standard Payment. |
+| `message` | string | Payment status message. |
+| `transactionId` | string | Transaction reference. |
+| `reference` | string | Merchant-side reference. |
+| `merchantAccount` | string | Merchant account ID. |
+| `amount` | number | Requested payment amount. |
+| `currency` | string | Requested currency. |
+| `paidAmount` | string/number | Actual amount paid. |
+| `paidCurrency` | string | Currency used for payment. |
+| `itemName` | string | Item name. |
+| `description` | string | Payment description. |
+| `receiptURL` | string/null | Receipt URL when available. |
+| `timestamp` | string/null | Payment timestamp when available. |
+
+---
+
+# 30. Payment Response — PreAuth
+
+A successful PreAuth response is similar to:
+
+```js
+{
+  success: true,
+  paymentType: 'PREAUTH',
+  title: 'Pre-Auth Approved!',
+  message: 'Pre-auth approved successfully!',
+  transactionId: 'ABCD-1238838',
+  reference: 'RESERVATION-12345',
+  invoiceId: 'ABCD-20384774',
+  merchantAccount: '0.0.001000',
+  amount: 50,
+  currency: 'USD',
+  approvedAmount: 32,
+  approvedCurrency: 'USD',
+  iso20022Response: '<?xml version="1.0"...',
+  sessionDuration: 8959
+}
+```
+
+Important fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | boolean | Whether authorization succeeded. |
+| `paymentType` | string | `PREAUTH`. |
+| `message` | string | Authorization status. |
+| `transactionId` | string | Transaction reference. |
+| `reference` | string | Merchant-side reference. |
+| `merchantAccount` | string | Merchant account ID. |
+| `amount` | number | Requested authorization amount. |
+| `currency` | string | Requested currency. |
+| `approvedAmount` | string/number | Authorized amount. |
+| `approvedCurrency` | string | Currency of the authorized amount. |
+
+---
+
+# 31. Recurring Payment Response
+
+A successful recurring response is similar to:
+
+```js
+{
+  success: true,
+  paymentType: 'RECURRING',
+  title: 'Recurring Approved!',
+  message: 'Recurring payment approved successfully!',
+  transactionId: '1687-20260602',
+  recurringToken: null,
+  reference: null,
+  invoiceId: 'INV-RECURRING-1780388213609',
+  receiptURL: 'https://qa.pay.dropp.cc/receipts/1687-20260602',
+  timestamp: '2026-06-02T08:17:03.539270201Z',
+  merchantAccount: '0.0.4646049',
+  amount: 1,
+  currency: 'USD',
+  approvedAmount: 1,
+  approvedCurrency: 'USD',
+  frequency: 'MONTHLY',
+  iso20022Response: '<?xml version="1.0"...'
+}
+```
+
+Important fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | boolean | Whether recurring authorization succeeded. |
+| `paymentType` | string | `RECURRING`. |
+| `message` | string | Authorization status. |
+| `transactionId` | string | Transaction reference. |
+| `reference` | string | Merchant-side reference. |
+| `merchantAccount` | string | Merchant account ID. |
+| `amount` | number | Requested amount. |
+| `currency` | string | Requested currency. |
+| `approvedAmount` | string/number | Approved recurring amount. |
+| `approvedCurrency` | string | Currency of the approved amount. |
+| `frequency` | string | Recurring interval. |
+
+For recurring flows, the merchant backend is responsible for securely storing the recurring token where applicable because it is required for future captures/recurring authorization according to the documented flow.
+
+---
+
+# 32. Failed Payment Handling
+
+A payment can fail in two ways:
+
+1. `Dropp.pay()` returns an unsuccessful response.
+2. `Dropp.pay()` rejects the Promise.
+
+Always handle both.
+
+```js
+try {
+  const result = await Dropp.pay(paymentOptions);
+
+  const isSuccess = result?.success === true || result?.status === 'success';
+  if (!isSuccess) {
+    console.error('Payment unsuccessful');
+    // Show failure UI
+  }
+} catch (error) {
+  console.error('Payment error', error);
+  // Handle SDK/runtime error
+}
+```
+
+Do not fulfill an order solely because the payment window closed or because the Promise was returned. Verify the payment state on the merchant backend.
+
+---
+
+# 33. Error Handling
+
+The SDK documents the following error codes.
+
+| Error Code | Meaning | Recommended Action |
+|---|---|---|
+| `INVALID_CONFIG` | Input or merchant validation failed. | Check required fields, environment, credentials, callback URL, and application configuration. |
+| `ALREADY_OPEN` | Another SDK flow is already active. | Wait for the active flow to finish or close it before starting another flow. |
+| `INIT_TIMEOUT` | Payment/status flow did not initialize within the expected time. | Check environment URL/connectivity and retry. |
+| `PAYMENT_TIMEOUT` | Payment did not complete within the expected time. | Ask the user to retry and verify backend payment state. |
+| `UNKNOWN_ERROR` | Unexpected runtime/processing error. | Log the details, retry if appropriate, and contact support if persistent. |
+| `SDK_NOT_INITIALIZED` | SDK method was called before `Dropp.init()`. | Initialize the SDK before using payment/account/page APIs. |
+
+### 33.1 Merchant Validation Error Details
+
+When merchant validation fails, SDK errors include structured fields in `error.details`, including backend response payload where available.
+
+Use both top-level message and details when logging:
+
+```js
+try {
+  await Dropp.init({ merchantId, apiKey, environment: 'sandbox' });
+} catch (error) {
+  console.error('Dropp init failed:', error?.message);
+  console.error('Dropp init details:', error?.details);
+}
+```
+
+The SDK message for validation failures may include HTTP status, backend `responseCode`, and a backend-reported reason when present.
+
+---
+
+# 34. Reserved Error Codes
+
+The SDK defines the following codes for compatibility/extension, but the documented implementation does not currently emit them as SDK errors:
+
+- `ORIGIN_MISMATCH`
+- `MESSAGE_VALIDATION_FAILED`
+- `IFRAME_BLOCKED`
+
+For these conditions, the SDK currently logs warnings/errors and ignores invalid messages.
+
+---
+
+# 35. Additional Errors
+
+Some SDK paths may throw standard JavaScript `Error` objects rather than the SDK's structured error format.
+
+Examples include:
+
+- SDK used outside a browser environment.
+- Missing constructor credentials such as `merchantId` or `apiKey`.
+- Failure while creating the modal iframe.
+
+The host application should therefore use `try/catch` around asynchronous SDK operations and should not assume every error has a Dropp-specific error code.
+
+---
+
+# 36. React Integration
+
+```js
+import { useEffect } from 'react';
+import { Dropp } from '@dropp.cc/payment-sdk';
+
+function App() {
+  useEffect(() => {
+    Dropp.init({
+      merchantId: 'YOUR_MERCHANT_ID',
+      apiKey: 'YOUR_API_KEY',
+      environment: 'production'
+    });
+  }, []);
+
+  const handlePayment = async () => {
+    try {
+      const result = await Dropp.pay({
+        amount: 99.99,
+        currency: 'USD',
+        itemName: 'Product Purchase',
+        paymentType: 'standard',
+        description: 'Product purchase',
+        invoiceId: 'ORDER-12345'
+      });
+
+      console.log(result);
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  return (
+    <button onClick={handlePayment}>
+      Pay with Dropp
+    </button>
+  );
+}
+```
+
+---
+
+# 37. Vanilla JavaScript Integration
+
+Include the SDK:
+
+```html
+<script src="https://unpkg.com/@dropp.cc/payment-sdk/dist/dropp-payment-sdk.js"></script>
+```
+
+Initialize:
+
+```js
+const { Dropp } = window.DroppPaymentSDK;
+
+Dropp.init({
+  merchantId: 'YOUR_MERCHANT_ID',
+  apiKey: 'YOUR_API_KEY',
+  environment: 'production'
+});
+```
+
+Execute a payment:
+
+```js
+const result = await Dropp.pay({
+  amount: 49.99,
+  currency: 'USD',
+  itemName: 'One-time Purchase',
+  paymentType: 'standard',
+  description: 'One-time purchase',
+  invoiceId: 'ORDER-12345'
+});
+```
+
+---
+
+# 38. Complete Host Application Example
+
+A typical host application can combine initialization, status, custom pages, and payments:
+
+```js
+import { Dropp } from '@dropp.cc/payment-sdk';
+
+Dropp.init({
+  merchantId: 'YOUR_MERCHANT_ID',
+  apiKey: 'YOUR_API_KEY',
+  environment: 'sandbox'
+});
+
+async function openWallet() {
+  Dropp.dashboard({
+    modules: [
+      'funding',
+      'accounts',
+      'transactions',
+      'settings',
+      'support'
+    ]
+  });
+}
+
+async function checkAccount() {
+  const status = await Dropp.status();
+
+  if (status?.data?.linked) {
+    console.log('Account is linked');
+  } else {
+    console.log('Account is not linked');
+  }
+}
+
+async function linkBank() {
+  Dropp.open('linkbank');
+}
+
+async function unlinkAccount() {
+  Dropp.unlinkAccount();
+}
+
+async function pay() {
+  try {
+    const result = await Dropp.pay({
+      amount: 49.99,
+      currency: 'USD',
+      itemName: 'Product Purchase',
+      paymentType: 'standard',
+      description: 'Product purchase',
+      invoiceId: 'ORDER-12345'
+    });
+
+    if (result?.status === 'success' || result?.success === true) {
+      console.log('Payment successful');
+    } else {
+      console.log('Payment unsuccessful');
+    }
+  } catch (error) {
+    console.error('Payment error', error);
+  }
+}
+```
+
+---
+
+# 39. Security Requirements
+
+The host application must follow these security practices:
+
+### Required
+
+- Use HTTPS in production.
+- Keep API credentials secure.
+- Keep private signing keys on the backend.
+- Verify transactions on the merchant backend.
+- Store merchant-side order/reference identifiers.
+- Use unique invoice/order identifiers.
+- Log payment events for auditing.
+- Validate payment status before fulfilling an order.
+
+### Do Not
+
+- Expose private signing keys in frontend code.
+- Hard-code backend signing secrets into browser JavaScript.
+- Trust only client-side payment state for order fulfillment.
+- Reuse invoice identifiers.
+
+---
+
+# 40. Backend Verification
+
+After a successful payment/authorization response, the merchant backend should:
+
+1. Verify the payment status.
+2. Validate transaction details.
+3. Match the payment with the merchant's order/reference.
+4. Update the order or subscription.
+5. Fulfill the order or activate the subscription.
+
+For recurring payments, the merchant should also maintain the subscription/authorization state and securely handle the recurring authorization information required for future billing.
+
+---
+
+# 41. Message/Event Flow
+
+Communication between the host application and the Dropp frame follows the documented message flow:
+
+```text
+READY
+  ↓
+Frame is loaded
+
+PAYMENT_INIT
+  ↓
+Host sends payment data
+
+PAYMENT_SUCCESS / PAYMENT_FAILED
+  ↓
+Dropp frame returns the result
+```
+
+The SDK is responsible for the iframe communication layer. The host application should consume the SDK APIs and callbacks rather than implementing the iframe messaging protocol directly.
+
+---
+
+# 42. Recommended Integration Patterns
+
+## Pattern A — One-Time Checkout
+
+Use:
+
+```js
+Dropp.init(...)
+Dropp.pay({
+  paymentType: 'standard',
+  ...
+})
+```
+
+Recommended for normal checkout.
+
+---
+
+## Pattern B — Temporary Authorization
+
+Use:
+
+```js
+Dropp.init(...)
+Dropp.pay({
+  paymentType: 'preauth',
+  callbackUrl: 'https://merchant.example.com/pre-auth-post-callback',
+  ...
+})
+```
+
+Recommended when the merchant needs authorization before the final charge.
+
+The merchant must provide the backend callback/signing infrastructure.
+
+---
+
+## Pattern C — Subscription
+
+Use:
+
+```js
+Dropp.init(...)
+Dropp.pay({
+  paymentType: 'recurring',
+  callbackUrl: 'https://merchant.example.com/rps-callback',
+  ...
+})
+```
+
+Recommended for recurring/subscription billing.
+
+The merchant must provide the backend callback/signing infrastructure.
+
+---
+
+## Pattern D — Wallet Management
+
+Use:
+
+```js
+Dropp.dashboard(...)
+```
+
+when the user needs access to several wallet features.
+
+---
+
+## Pattern E — Deep Link
+
+Use:
+
+```js
+Dropp.open('transactions');
+Dropp.open('linkbank');
+Dropp.open('profile');
+```
+
+when the host application wants to take the user directly to a specific page.
+
+---
+
+## Pattern F — Account State Check
+
+Use:
+
+```js
+const status = await Dropp.status();
+```
+
+when the host application needs to determine whether the user's Dropp account is linked before presenting the next action.
+
+---
+
+# 43. Testing Checklist
+
+## Prerequisites
+
+- [ ] Merchant account is active.
+- [ ] KYC is completed.
+- [ ] Correct Merchant ID is available.
+- [ ] API Key is generated.
+- [ ] Host domain/package name is registered.
+- [ ] Package/domain configuration matches the host application.
+
+## SDK Initialization
+
+- [ ] Correct environment selected.
+- [ ] Correct Merchant ID configured.
+- [ ] Correct API Key configured.
+- [ ] Package Name/Domain configured.
+- [ ] SDK initializes without errors.
+
+## Standard Payment
+
+- [ ] Successful payment tested.
+- [ ] Failed payment tested.
+- [ ] Cancelled payment tested.
+- [ ] Backend verification tested.
+- [ ] Order fulfillment tested.
+
+## PreAuth
+
+- [ ] Public HTTPS callback URL configured.
+- [ ] Merchant backend is running.
+- [ ] Dropp Backend SDK is configured.
+- [ ] Signing flow verified.
+- [ ] Authorization hold duration tested.
+- [ ] Authorization expiration tested.
+- [ ] Failed callback/signing scenario tested.
+
+## Recurring
+
+- [ ] Public HTTPS callback URL configured.
+- [ ] Merchant backend is running.
+- [ ] Recurring authorization signing verified.
+- [ ] Supported frequency tested.
+- [ ] `recurringEndDate` tested.
+- [ ] Recurring authorization response handled.
+- [ ] Future authorization/capture handling verified.
+
+## Account APIs
+
+- [ ] `status()` tested for linked account.
+- [ ] `status()` tested for unlinked account.
+- [ ] Bank linking tested.
+- [ ] Card linking tested.
+- [ ] Unlink flow tested.
+
+## Custom Pages
+
+- [ ] Dashboard opens correctly.
+- [ ] Configured modules appear correctly.
+- [ ] Direct page navigation tested.
+- [ ] Transactions page tested.
+- [ ] Profile page tested.
+- [ ] Funding pages tested.
+- [ ] Offers page tested.
+
+## Security
+
+- [ ] HTTPS enabled.
+- [ ] Private signing key remains on backend.
+- [ ] Backend payment verification implemented.
+- [ ] Secrets are not exposed to frontend.
+- [ ] Unique order/reference identifiers are used.
+
+---
+
+# 44. Troubleshooting
+
+## Payment Window Does Not Open
+
+Verify:
+
+- SDK initialization completed successfully.
+- Required parameters are present.
+- Merchant ID is correct.
+- API Key is correct.
+- Environment matches the credentials.
+- Host domain/package name is correctly registered.
+- Browser console contains no errors.
+- Another SDK flow is not already active.
+
+---
+
+## `SDK_NOT_INITIALIZED`
+
+Cause:
+
+```text
+Dropp.pay()
+Dropp.status()
+Dropp.dashboard()
+Dropp.open()
+```
+
+or another SDK API was called before initialization.
+
+Solution:
+
+```js
+Dropp.init({
+  merchantId: 'YOUR_MERCHANT_ID',
+  apiKey: 'YOUR_API_KEY',
+  environment: 'sandbox'
+});
+```
+
+Call SDK functionality only after initialization has completed.
+
+---
+
+## Callback Not Triggered
+
+For PreAuth and recurring payments, verify:
+
+- Callback URL is correct.
+- Callback URL is publicly accessible.
+- HTTPS is enabled.
+- Backend application is running.
+- Backend endpoint is mapped to the expected callback route.
+- Backend returns the expected signed response.
+- Merchant ID and signing key are correctly configured.
+
+---
+
+## Invalid Merchant Error
+
+Verify:
+
+- Merchant ID is correct.
+- API Key belongs to the same environment.
+- Host application/domain configuration is registered.
+- Host application is running on the registered domain.
+- Sandbox credentials are not being used against production.
+
+---
+
+## Environment Mismatch
+
+Verify that credentials and wallets match the environment:
+
+```text
+Sandbox → Sandbox Merchant ID + Sandbox API Key + Sandbox Wallet
+Production → Production Merchant ID + Production API Key + Production Wallet
+```
+
+---
+
+# 45. Browser Support
+
+| Browser | Minimum Version |
+|---|---:|
+| Chrome | 90+ |
+| Firefox | 88+ |
+| Safari | 14+ |
+| Edge | 90+ |
+
+---
+
+# 46. Go-Live Checklist
+
+Before launching the SDK integration in production:
+
+- [ ] KYC approved.
+- [ ] Production Merchant ID received.
+- [ ] Production API Key generated.
+- [ ] Production host domain/package name approved.
+- [ ] Production environment selected.
+- [ ] Backend payment verification implemented.
+- [ ] PreAuth callback endpoint tested, if applicable.
+- [ ] Recurring callback endpoint tested, if applicable.
+- [ ] Successful Standard Payment tested.
+- [ ] Failed/cancelled payment scenarios tested.
+- [ ] Account linking tested.
+- [ ] Account unlinking tested.
+- [ ] Status API tested.
+- [ ] Custom dashboard/pages tested.
+- [ ] HTTPS enabled.
+- [ ] Private signing credentials remain on the backend.
+- [ ] End-to-end payment verification completed.
+
+---
+
+# 47. SDK API Quick Reference
+
+| API | Purpose | When to Use |
+|---|---|---|
+| `Dropp.init()` | Initialize SDK | Always, before using SDK functionality |
+| `Dropp.pay()` | Start payment | Standard, PreAuth, or recurring payment |
+| `Dropp.status()` | Check linked account status | Before account-dependent UI/actions |
+| `Dropp.open()` | Open a specific Dropp page | Deep-link to a particular task |
+| `Dropp.dashboard()` | Open full/selected wallet dashboard | Give user access to wallet functions, including account linking |
+| `Dropp.unlinkAccount()` | Open unlink-account UI | Remove a linked funding source |
+| `Dropp.closePayment()` | Close payment window | Programmatic payment-window control |
+| `Dropp.getVersion()` | Get SDK version | Diagnostics/support |
+| `Dropp.getEnvironments()` | Get supported environment strings | Environment/diagnostic logic |
+| `Dropp.getInstance()` | Get initialized SDK instance | SDK state/diagnostics |
+
+### Account Linking Quick Reference
+
+```js
+// Open Dashboard for account linking / wallet management
+Dropp.dashboard();
+
+// Check account status
+const status = await Dropp.status();
+
+// Unlink funding source
+Dropp.unlinkAccount();
+```
+
+### Custom Page Quick Reference
+
+```js
+Dropp.open('fundnow');
+Dropp.open('linkbank');
+Dropp.open('linkcard');
+Dropp.open('redeemnow');
+Dropp.open('fundcrypto');
+Dropp.open('transferusdc');
+Dropp.open('usdchistory');
+Dropp.open('redeemcrypto');
+Dropp.open('manageaccounts');
+Dropp.open('transactions');
+Dropp.open('merchantlist');
+Dropp.open('favorites');
+Dropp.open('offers');
+Dropp.open('profile');
+Dropp.open('pinchange');
+Dropp.open('aboutus');
+```
+
+# 48. Support
+
+For technical assistance, contact:
+
+```text
+support@dropp.cc
+```
+
+Include the following information when reporting an issue:
+
+- Merchant ID.
+- Environment.
+- SDK version.
+- Error code/message.
+- Browser and browser version.
+- Host application/framework.
+- Payment type.
+- Reproduction steps.
+- Relevant request/response details that do not expose secrets.
+
+---
+
+# 49. Important Documentation Note
+
+This guide is based on the currently supplied SDK integration documentation.
+
+The supplied material explicitly documents:
+
+- `Dropp.init()`
+- `Dropp.pay()`
+- `Dropp.status()`
+- `Dropp.dashboard()`
+- `Dropp.open()`
+- `Dropp.unlinkAccount()`
+- `Dropp.closePayment()`
+- `Dropp.getVersion()`
+- `Dropp.getEnvironments()`
+- `Dropp.getInstance()`
+
+The SDK does **not** expose a separate `Dropp.linkAccount()` method. Account linking is handled through the Dropp Dashboard, which should be opened using `Dropp.dashboard()`. The host application can use `Dropp.status()` to determine whether the account is already linked.
+
+Similarly, custom-page-specific parameters/callbacks should only be added when they are supported by the SDK implementation.
+
+This keeps the documentation aligned with the actual SDK contract and avoids promising APIs that are not currently documented.
+
+---
+
+# 50. Platform Constraints and Advanced Contracts
+
+This section documents current behavior and integration constraints that are important for production readiness.
+
+## 50.1 Refund API Availability
+
+The Web SDK currently does not expose a dedicated refund API method.
+
+If your product requires refunds, implement refund operations through your backend/payment operations workflow.
+
+## 50.2 PreAuth Lifecycle Coverage
+
+Current documented SDK flow covers creating a pre-authorization hold.
+
+Capture/settlement and explicit release/void operations are backend lifecycle operations and must be implemented using backend contracts for your environment.
+
+Sandbox behavior can enforce one active preauth hold per payer until completion/expiry/cancellation.
+
+## 50.3 Callback Envelope and Submission Contract
+
+For recurring and preauth callback routes, host backend should normalize incoming payload to a common envelope:
+
+```json
+{
+  "data": "<base64 payload>",
+  "signatures": {
+    "payer": "<payer signature>"
+  }
+}
+```
 
-- Chrome 90+
-- Firefox 88+
-- Safari 14+
-- Edge 90+
+Then submit server-to-server to the authoritative backend endpoint for that flow, persist authoritative response data, and only then return callback approval.
 
-## Troubleshooting
+## 50.4 Recurring Token Handling
 
-### Payment modal doesn't open
+Recurring callback/SDK responses can vary by environment and flow outcome. `recurringToken` preserve that token in respect of user account.
 
-- Check browser console for errors
-- Verify all required fields are provided
-- Ensure `merchantAccount` format is correct (`"0.0.123456"`)
+Always treat backend authoritative submission response as source of truth for token persistence and future recurring lifecycle operations.
 
-### Messages not received
+## 50.5 Known Limits and Constraints
 
-- Check that you're using the correct environment
-- Verify origin validation isn't blocking legitimate messages
-- Check browser console for message validation errors
+Known limits to account for in product design/testing:
 
-### TypeScript errors
+1. PreAuth hold duration is time-limited and should be treated as short-lived authorization.
+2. `authHoldTimeInSeconds` is typically constrained to 86400 seconds (24 hours).
+3. payment amount can be constrained to 1000 (environment policy).
+4. Concurrent SDK flows are blocked by single-session locking (`ALREADY_OPEN`).
 
-- Ensure you have `@dropp/payment-sdk` installed
-- If you use TypeScript types, import them from `@dropp/payment-sdk`
+Validate these constraints in your target environment before go-live.
 
-## Support
+## 50.6 Server-Side Verification Requirement
 
-For issues or questions:
-- Email: support@dropp.cc
+Do not treat client callback success alone as final settlement/authorization proof.
 
+Backend must verify and persist authoritative transaction state before order fulfillment.
 
-MIT License - see LICENSE file for details
+## 50.7 Sandbox Display Name Behavior
 
-## Changelog
+In sandbox, hosted transaction UIs may show merchant display name configured in sandbox merchant profile rather than host-app branding.
 
-### v1.0.0 (2026-06-01)
-- Initial release
-- Standard, preauth, and recurring payment support
-- Secure postMessage communication
-- Framework-agnostic design
-- Full TypeScript definitions
+Treat this as environment behavior and verify production branding/configuration separately.
 
-### v1.0.3 (2026-07-06)
-- Added Support for the Home/Dashboard.
+## 50.8 PreAuth One-Active Rule and Cancellation
 
-### v1.0.4 (2026-07-07)
-- Added Support for the Unlink account.
+If an environment enforces one active preauth per payer, repeated preauth attempts can fail until existing hold is completed, expired, or cancelled.
 
-### v1.0.5 (2026-07-09)
-- Added Support for the Transactions.
-- Added Support for the Offers.
-- Added Support for Security before open any customized method.
+Ensure your backend includes handling for:
 
-### v1.0.10 (2026-07-10)
-- Added Support for the 404 methods.
-- Added Support for the status check. 
+1. Active-hold conflict responses.
+2. Cancellation/release operations where supported by your backend contract.
+3. Reconciliation between hosted approval UI and backend authoritative hold state.
 
-### v1.0.20 (2026-07-27)
-- Added qa and sandbox api gateway support.
-- Whitelabeling of the merchants.
+Observed sandbox integrations have used a release/cancel path such as `/api/rps/v1/payments/preAuth/p2p/process` with `action: "CANCEL"`; validate official contract availability for your target environment before production use.