Integration Workflow Guide

This guide walks you through the complete integration workflow, from onboarding new customers through checkout to managing existing subscriptions. Follow these steps to seamlessly integrate UniBee into your application.

Overview

The integration workflow consists of two main phases:

New Customer Onboarding - Getting customers signed up through UniBee checkout
Subscription Management - Allowing customers to view and manage their subscriptions

🚀 Quick Integration: UniBee Hosted Pages (Recommended)

To minimize integration effort and accelerate time-to-market, UniBee provides two ready-to-use hosted pages:

Feature	Integration Effort	Use Case
Checkout Purchases (Hosted Mode)	Minimal - Copy checkout link and configure return URL	First-time purchases, zero frontend code required
Change Subscription (Hosted Mode)	Low - One API call to generate hosted page URL	Subscription management (upgrade, downgrade, renew, cancel)

Why use Hosted Pages?

✅ Hours to days vs weeks to months of custom development
✅ PCI compliant - UniBee handles payment security
✅ Mobile optimized - Responsive design out of the box
✅ Conversion optimized - Tested checkout flows
✅ Focus on core business - UniBee handles billing infrastructure

💡 Recommendation: Start with hosted pages for fast integration. You can always build custom UI using UniBee’s APIs later if needed.

Part 1: New Customer Onboarding

💡 Quick Start: This phase uses UniBee’s Checkout Purchases (Hosted Mode) - a fully functional hosted checkout page that requires zero frontend code and minimal integration effort.

Step 1: Using Checkout Links

UniBee provides checkout links for each active Plan. These links enable customers to complete purchases without requiring authentication in your system.

Access Location: Copy the checkout link from the Plan definition page in UniBee Admin Portal
Usage: Direct customers to the checkout link to initiate their first purchase
No Authentication Required: Customers can complete checkout without being logged into your system

Key Benefits of Hosted Checkout:

Zero frontend code required
PCI compliance handled automatically
Mobile-optimized and conversion-tested
Handles payment processing and customer information collection

For more details, see Checkout Purchases (Hosted Mode).

Step 2: Handling Return URL After Purchase

After a customer successfully completes checkout, UniBee redirects them back to your system using the Return URL configured at the Product definition page. Return URL Format:

${returnUrl}?email={Customer Email}&paymentId={UniBeePaymentId}&subId={UniBeeSubscriptionId}&invoiceId={UniBeeInvoiceId}&success=true

URL Parameters:

Parameter	Description
`email`	The customer’s email address
`paymentId`	The UniBee payment ID generated for this purchase
`subId`	The UniBee subscription ID created for the customer
`invoiceId`	The UniBee invoice ID for the initial invoice
`success`	Boolean flag indicating successful checkout completion

Implementation Example:

// Parse return URL parameters
const urlParams = new URLSearchParams(window.location.search);
const email = urlParams.get('email');
const paymentId = urlParams.get('paymentId');
const subId = urlParams.get('subId');
const invoiceId = urlParams.get('invoiceId');
const success = urlParams.get('success') === 'true';

if (success) {
  // Proceed with onboarding logic
  handleOnboarding(email, subId, invoiceId);
}

Step 3: Completing Your Business Logic

After receiving the return callback, complete your system’s onboarding workflow:

Customer Registration: Create the customer account in your system using the email from the return URL
Password Setup: Prompt the customer to set up their password
Account Activation: Activate the customer’s account and grant access

You can retrieve detailed customer and subscription information using one of the following methods:

Option A: Using Invoice API

Use the invoiceId from the return URL to fetch complete invoice details:

curl --location --request GET "$UniBee_API_Host/merchant/invoice/invoice_detail" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceId": "$invoiceId"
  }'

The response includes:

Customer details (email, name, billing address)
Subscription information
Payment details
Invoice line items

See Invoice API Reference for detailed response schema.

Option B: Using Subscription API

Alternatively, use the subId to fetch subscription details:

curl --location --request GET "$UniBee_API_Host/merchant/subscription/subscription_detail" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "subscriptionId": "$subId"
  }'

See Subscription API Reference for detailed response schema.

Step 4: Setting Up Webhooks (Recommended)

For a robust integration, subscribe to UniBee webhook events. This ensures your system stays synchronized even if the return URL callback fails or is delayed. Recommended Webhook Events:

Event	Description	When It Fires
`subscription.activate`	Subscription becomes active	After customer completes checkout (or when subscription is assigned and payment succeeds)
`invoice.paid`	Invoice payment successful	Whenever any invoice payment completes successfully
`user.metric.update`	User’s plan metrics changed	When the customer’s subscription plan changes

Quick Setup Steps:

Create Webhook Endpoint in UniBee Admin Portal:
- Navigate to Configuration → Webhooks → Webhook Endpoints
- Click Add Webhook Endpoint
- Enter your endpoint URL (e.g., https://yourdomain.com/webhooks/unibee)
- Select the events listed above
Verify Webhook Requests: UniBee provides two verification methods:
- API Key Verification: Check the Authorization header contains your API key (simpler)
- HMAC Signature Verification: Validate the X-Signature header using HMAC-SHA256 (more secure) You can choose either method or implement both for maximum security.
Handle Webhook Events: Process incoming events based on the EventType header
Return Response: Your endpoint must return HTTP 200 with body content “success”

📚 For detailed implementation guide, code examples, and complete verification documentation, see Webhooks Documentation

For a list of all available webhook events, see Webhook Events.

Part 2: Subscription Management for Existing Customers

💡 Quick Start: For subscription management, UniBee provides Change Subscription (Hosted Mode) - a secure hosted page that handles upgrades, downgrades, renewals, cancellations, and payment method updates with minimal integration (just one API call).

Once customers have completed onboarding and logged into your system, you can provide them with tools to view and manage their subscriptions.

Step 1: Displaying Customer Profile

Retrieve the customer’s subscription details to build a comprehensive profile UI: API Endpoint: Get User Subscription Detail

curl --location --request GET "$UniBee_API_Host/merchant/subscription/user_subscription_detail" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com"
  }'

Response Includes:

Current subscription status
Active plan details
Billing cycle information
Next billing date
Payment method
Invoice history
Usage metrics (if applicable)

UI Elements to Display:

Current plan name and pricing
Subscription status badge (Active, Cancelled, Pending, etc.)
Next billing date and amount
Billing cycle (monthly, yearly, etc.)
Payment method on file
Recent invoices with download links

Step 2: Building Pricing UI

Create a pricing page that shows available plans:

Fetch Available Plans: Use the Get Plan List API to retrieve all active plans
Display Plans: Show plan features, pricing, and billing cycles
Highlight Current Plan: Indicate which plan the customer is currently subscribed to
Action Buttons: Provide “Upgrade” or “Downgrade” buttons for each plan

Step 3: Handling Plan Changes (Upgrade, Downgrade, Renew)

When a customer selects a new plan, redirect them to UniBee’s Subscription Update Hosted Page. This hosted page handles all subscription changes securely with built-in authentication and real-time previews. Benefits:

One API call to generate the hosted page URL
Handles all subscription lifecycle operations (upgrade, downgrade, renew, cancel)
Secure user authentication built-in
Shows customers exactly what changes will occur before confirming

Implementation: Step 3a: Generate Update Page URL Call the Session API to get the hosted update page URL: API Endpoint: Get User Subscription Update Page URL

curl --location --request POST "$UniBee_API_Host/merchant/session/user_sub_update_url" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "customer@example.com",
    "externalUserId": "your_user_id_123",
    "planId": 456,
    "productId": 789,
    "returnUrl": "https://yourdomain.com/subscription/update-success",
    "cancelUrl": "https://yourdomain.com/subscription/update-cancelled",
    "vatCountryCode": "US"
  }'

Response:

{
  "code": 0,
  "data": {
    "url": "https://cs.unibee.dev/hosted/sub_update?session=xxx&env=prod"
  }
}

Step 3b: Redirect Customer Redirect the customer to the URL from the API response:

// User clicks "Upgrade to Pro Plan"
const response = await fetch('/api/get-update-url', {
  method: 'POST',
  body: JSON.stringify({
    email: customerEmail,
    planId: targetPlanId,
    returnUrl: 'https://yourdomain.com/subscription/update-success'
  })
});

const { url } = await response.json();
window.location.href = url; // Redirect to UniBee hosted page

Step 3c: Handle Return Callback After the customer completes the update on UniBee’s hosted page, they’ll be redirected back to your returnUrl. Handle the callback similar to the checkout return:

// Handle return from subscription update
const urlParams = new URLSearchParams(window.location.search);
const success = urlParams.get('success') === 'true';

if (success) {
  // Refresh subscription details
  await refreshSubscriptionDetails();
  // Show success message
  showNotification('Subscription updated successfully!');
}

What Happens Behind the Scenes:

UniBee creates a PendingUpdate record (subscription doesn’t change immediately)
Customer completes payment on the hosted page
After successful payment:
- Webhook events are sent: subscription.pending_update.success, invoice.paid, subscription.update.success
- Subscription status updates to reflect the new plan
- New billing cycle begins

For more details, see Change Subscription After Purchases (Hosted Mode).

Testing with Sandbox

Before going live, test your integration using UniBee’s Sandbox environment:

Use Sandbox API: Point your integration to https://api-sandbox.unibee.top
Configure Sandbox Checkout Links: Use sandbox checkout links (they’ll have env=sandbox in the URL)
Test Webhooks:
- Option A: Deploy your webhook endpoint to a public URL (e.g., a staging server or cloud function)
- Option B: Use a local development tool (e.g., ngrok, localtunnel, or similar) to temporarily expose your local webhook endpoint to the internet
- Webhook URL Requirements: Your webhook endpoint must be publicly accessible via HTTPS URL. UniBee will send POST requests to your configured webhook URL.
Test Payment Flows: Use test cards (see Testing Cards)
Simulate Subscription Events: Use UniBee’s subscription simulation feature to quickly test subscription lifecycle events (invoices, renewals, etc.) without waiting for real-time intervals. This allows you to advance time and observe how subscriptions behave over extended periods. See Simulate Subscriptions (Sandbox) for detailed instructions.
Verify Webhook Events: Monitor webhook deliveries in UniBee Admin Portal to ensure events are received correctly

Integration Checklist

Use this checklist to ensure your integration is complete:

Onboarding Flow

Checkout links configured and accessible
Return URL configured at Product level
Return URL parameters parsed correctly
Customer registration logic implemented
Password setup flow completed
Invoice/Subscription API integration for fetching details
Webhook endpoint configured
Webhook signature verification implemented
Webhook event handlers for subscription.activate, invoice.paid, user.metric.update

Subscription Management

User subscription detail API integrated
Profile UI displaying subscription information
Pricing page with available plans
Subscription update page URL generation implemented
Redirect to UniBee hosted update page working
Return URL handling for update completion
Webhook handlers for update-related events

Testing

Sandbox environment tested
Test cards used for payment flows
Webhook events verified
Error handling implemented
Edge cases tested (cancelled subscriptions, failed payments, etc.)

Overview

Quick start

Billable metric

Define Products and Plans

Discount code

Subscription

Invoices

Transaction

User management

Admin management

Webhooks

Reports and export reports

Promo Credit

Overview

🚀 Quick Integration: UniBee Hosted Pages (Recommended)

Part 1: New Customer Onboarding

Step 1: Using Checkout Links

Step 2: Handling Return URL After Purchase

Step 3: Completing Your Business Logic

Option A: Using Invoice API

Option B: Using Subscription API

Step 4: Setting Up Webhooks (Recommended)

Part 2: Subscription Management for Existing Customers

Step 1: Displaying Customer Profile

Step 2: Building Pricing UI

Step 3: Handling Plan Changes (Upgrade, Downgrade, Renew)

Testing with Sandbox

Integration Checklist

Onboarding Flow

Subscription Management

Testing

Overview

Quick start

Billable metric

Define Products and Plans

Discount code

Subscription

Invoices

Transaction

User management

Admin management

Webhooks

Reports and export reports

Promo Credit

​Overview

​🚀 Quick Integration: UniBee Hosted Pages (Recommended)

​Part 1: New Customer Onboarding

​Step 1: Using Checkout Links

​Step 2: Handling Return URL After Purchase

​Step 3: Completing Your Business Logic

​Option A: Using Invoice API

​Option B: Using Subscription API

​Step 4: Setting Up Webhooks (Recommended)

​Part 2: Subscription Management for Existing Customers

​Step 1: Displaying Customer Profile

​Step 2: Building Pricing UI

​Step 3: Handling Plan Changes (Upgrade, Downgrade, Renew)

​Testing with Sandbox

​Integration Checklist

​Onboarding Flow

​Subscription Management

​Testing

​Related Documentation

Overview

🚀 Quick Integration: UniBee Hosted Pages (Recommended)

Part 1: New Customer Onboarding

Step 1: Using Checkout Links

Step 2: Handling Return URL After Purchase

Step 3: Completing Your Business Logic

Option A: Using Invoice API

Option B: Using Subscription API

Step 4: Setting Up Webhooks (Recommended)

Part 2: Subscription Management for Existing Customers

Step 1: Displaying Customer Profile

Step 2: Building Pricing UI

Step 3: Handling Plan Changes (Upgrade, Downgrade, Renew)

Testing with Sandbox

Integration Checklist

Onboarding Flow

Subscription Management

Testing

Related Documentation