Skip to main content

Billing Quick Start

Get up and running with Hyve SDK billing in 5 minutes.

1. Install Dependencies​

npm install @hyve-sdk/js

2. Initialize HyveClient with Billing​

import { HyveClient } from '@hyve-sdk/js';

const client = new HyveClient({
  billing: {
    stripePublishableKey: 'pk_test_...'  // Your Stripe key (required for web)
  }
});

// Authenticate from URL (extracts user and game info)
await client.authenticateFromUrl();

// Initialize billing (auto-configures with user/game data)
await client.initializeBilling();

3. Add Checkout Container (Web Only)​

Add this to your HTML for web (Stripe) payments:

<div id="stripe-checkout-element"></div>

4. Set Up Event Handlers​

client.onPurchaseComplete((result) => {
  console.log('Success!', result);
  // Credit items to user
});

client.onPurchaseError((result) => {
  console.error('Failed:', result.error);
  // Show error message
});

5. Display Products​

const products = await client.getBillingProducts();

products.forEach(product => {
  console.log(`${product.title}: ${product.localizedPrice}`);
});

6. Make a Purchase​

// Web: Mounts Stripe checkout form
// Native: Shows native IAP dialog
await client.purchaseProduct(productId, {
  elementId: 'stripe-checkout-element' // Web only, optional
});

Complete Example​

import { HyveClient } from '@hyve-sdk/js';

async function setupBilling() {
  // 1. Initialize client with billing config
  const client = new HyveClient({
    billing: {
      stripePublishableKey: process.env.STRIPE_PUBLIC_KEY
    }
  });

  // 2. Authenticate (auto-extracts user ID and game ID from URL)
  await client.authenticateFromUrl();

  // 3. Initialize billing (auto-configures with user/game data)
  await client.initializeBilling();

  // 4. Set up callbacks
  client.onPurchaseComplete((result) => {
    showSuccessMessage('Purchase complete!');
  });

  client.onPurchaseError((result) => {
    showErrorMessage(result.error.message);
  });

  // 5. Load and display products
  const products = await client.getBillingProducts();
  renderProductList(products);

  return client;
}

// Usage
const client = await setupBilling();

// When user clicks buy
function handleBuyClick(productId) {
  client.purchaseProduct(productId, {
    elementId: 'checkout-container'
  });
}

Testing Locally​

Web Testing​

  1. Start your app with URL params:

    http://localhost:3000?game-id=1&hyve-access=JWT_TOKEN

  2. Use Stripe test card:

    Card: 4242 4242 4242 4242
    Expiry: Any future date
    CVC: Any 3 digits

Native Testing​

  1. Load in React Native WebView:

    <WebView source={{ uri: 'http://YOUR_IP:3000?game-id=1' }} />

  2. Use test products from app store console

Server Requirements​

Your API needs these endpoints:

  • GET /get-packages?game_id={id} - Web products
  • GET /get-native-packages?game_id={id} - Native products
  • POST /create-checkout-session - Create Stripe session
  • POST /iap/validate - Validate IAP receipts

See full API documentation for details.

Next Steps​

Common Issues​

Q: Initialization fails on web A: Ensure stripePublishableKey is provided and valid

Q: Products not loading A: Verify gameId exists and API endpoints return correct format

Q: Purchase fails on native A: Ensure app is installed from store, not development build

Q: Platform shows "unknown" A: Check WebView setup for native or browser compatibility for web