Dropp Payment SDK for Web

A secure, production-ready JavaScript SDK for integrating Dropp payments into web applications.

Features

• 🔒 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

Installation

Install the SDK using npm:

npm install @dropp/payment-sdk

Initialization

Dropp.init(config)

Initializes the SDK with the required configuration.

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'.

Example:

Dropp.init({
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'YOUR_API_KEY',
  packageName: 'com.example.webapp',
  environment: 'production',
});

Payment

Dropp.pay(options)

Initiates a payment process.

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.

Example:

Dropp.pay({
  merchantAccount: '0.0.123456',
  amount: 100.00,
  currency: 'USD',
  itemName: 'Premium Subscription',
  paymentType: 'standard',
  callbackUrl: 'https://example.com/callback'
});

Environments

The SDK supports the following environments:

• 'production': For live transactions.
• 'qa': For quality assurance testing.
• 'sandbox': For development and testing.

Ensure you use the appropriate environment for your use case.

import '@dropp/payment-sdk';

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
});

Dropp.init({
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'YOUR_API_KEY',
  packageName: 'com.example.webapp',
  environment: 'production' // For live payments (mainnet)
});

Payment Examples

Standard Payment

Dropp.pay({
  merchantAccount: '0.0.123456',
  amount: 49.99,
  currency: 'USD',
  itemName: 'Premium Plan',
  description: 'One-time purchase',
  invoiceId: 'INV-2024-001'
});

Pre-Authorization Payment

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'
});

Recurring Payment

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'
});

React Integration

import { useEffect, useState } from 'react';
import { Dropp } from '@dropp/payment-sdk';

function CheckoutButton() {
  const [isProcessing, setIsProcessing] = useState(false);

  useEffect(() => {
    Dropp.init({
      merchantId: 'YOUR_MERCHANT_ID',
      apiKey: 'YOUR_API_KEY',
      packageName: 'com.example.webapp',
      environment: 'production'
    });
  }, []);

  const handlePayment = async () => {
    setIsProcessing(true);

    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);
    }
  };

  return (
    <button onClick={handlePayment} disabled={isProcessing}>
      {isProcessing ? 'Processing...' : 'Pay Now'}
    </button>
  );
}

Vanilla JavaScript Integration

Use this when you are not using React/Vue/Angular.

<!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'
      });

      document.getElementById('payStandard').addEventListener('click', async () => {
        await Dropp.pay({
          merchantAccount: '0.0.123456',
          amount: 49.99,
          currency: 'USD',
          itemName: 'One-time Purchase',
          paymentType: 'standard'
        });
      });

      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'
        });
      });

      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>

Security

The SDK implements multiple security layers:

✅ 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

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

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Troubleshooting

Payment modal doesn't open

• Check browser console for errors
• Verify all required fields are provided
• Ensure merchantAccount format is correct ("0.0.123456")

Messages not received

• Check that you're using the correct environment
• Verify origin validation isn't blocking legitimate messages
• Check browser console for message validation errors

TypeScript errors

• Ensure you have @dropp/payment-sdk installed
• If you use TypeScript types, import them from @dropp/payment-sdk

Support

For issues or questions:

• Email: [email protected]

MIT License - see LICENSE file for details

Changelog

v1.0.0 (2026-06-01)

• Initial release
• Standard, preauth, and recurring payment support
• Secure postMessage communication
• Framework-agnostic design
• Full TypeScript definitions