Hosted Self-Serve Portal
Integrate Portal

Integrate Portal

This guide explains how to integrate the BillHive Hosted Self-Serve Portal into your application.

Integration Options

BillHive provides two approaches to embed the portal:

1. API-Based Integration (SSO) — Recommended

Use the Portal Session API to generate authenticated portal sessions for your customers. This approach provides a seamless Single Sign-On (SSO) experience.

How it works:

  1. Customer logs into your application using your existing authentication.
  2. Your backend calls the BillHive Portal Session API to generate a session URL.
  3. Redirect the customer to the portal session URL or open it in an iframe.

Example: Create a Portal Session

curl https://api.billhive.org/v1/portal_sessions \
  -X POST \
  -u {api_key}: \
  -d customer_id="cust_abc123"

Response:

{
  "portal_session": {
    "id": "ps_xyz789",
    "token": "portal_tkn_...",
    "access_url": "https://yoursite.billhive.org/portal/session/ps_xyz789",
    "status": "active",
    "expires_at": 1700000000
  }
}

Important: Portal session URLs expire 1 hour after creation. Always generate a fresh session URL when the customer needs access.

Redirect to Portal:

// After creating the portal session on your backend
const portalSession = await createPortalSession(customerId);
window.location.href = portalSession.access_url;

Open in Iframe:

<iframe
  src="PORTAL_SESSION_ACCESS_URL"
  width="100%"
  height="800"
  frameborder="0"
  allow="payment"
></iframe>

2. Drop-In Script Integration

The quickest way to get started — no backend code required. BillHive handles all authentication using its native login (email + OTP).

Best for:

  • Quick prototyping
  • Applications without a custom authentication system

Add the script to your page:

<script src="https://js.billhive.org/portal/v1/billhive-portal.js"></script>

Initialize the portal:

<script>
  BillHive.portal.init({
    site: "your-site-name"
  });
</script>
 
<a href="javascript:void(0)" onclick="BillHive.portal.open()">
  Manage Subscription
</a>

When clicked, this opens the portal in a modal. The customer authenticates via BillHive's email + OTP flow.

Authentication Flows

SSO Flow (API-Based)

Customer → Your App Login → Your Backend → BillHive API (create session) → Portal URL → Customer accesses portal

No additional login step is required — the customer is already authenticated through your system.

BillHive Login Flow (Drop-In)

Customer → Clicks "Manage Subscription" → Enters email → Receives OTP → Enters OTP → Portal access

Multiple Accounts

If a customer's email is linked to multiple accounts:

  1. After authentication, the portal displays an account selection screen.
  2. The customer selects their desired account.
  3. The portal loads with that account's subscription and billing data.

You can improve the account selection experience by configuring account labels (e.g., company name, first name) under Settings > Hosted Pages > Labels.

Portal URL

Your portal is accessible at:

https://{your-site}.billhive.org/portal

Share this URL with customers for direct access (uses BillHive Login).

Security Considerations

  • Session Expiry: API-generated portal sessions expire after 1 hour.
  • 3D Secure: Payment method updates and charges within the portal trigger 3DS verification when applicable.
  • HTTPS: All portal communication is encrypted over HTTPS.
  • OTP Verification: The drop-in integration uses one-time passwords for secure authentication.

Testing

  1. Enable the portal in your test environment first.
  2. Use the Preview Portal button in Settings to test the customer experience.
  3. Create a test customer and verify all enabled features work correctly.
  4. Once satisfied, enable the portal in your live environment.

Next Steps

Portal FeaturesIntegrations