KuvarPay Subscriptions Guide

This guide explains how to implement and manage subscriptions using the KuvarPay Business Platform. KuvarPay supports both FIXED (recurring) and METERED (usage-based) billing models to accommodate different business needs.

Overview

KuvarPay's subscription system enables businesses to:

Create recurring payment plans with fixed pricing

Implement usage-based billing for metered services

Manage customer subscriptions and invoices

Handle payment authorization and collection automatically

Receive real-time webhook notifications for subscription events

Billing Modes

FIXED Billing Mode

FIXED billing is for traditional recurring subscriptions where customers pay a predetermined amount at regular intervals (monthly, yearly, etc.).

Use Cases:

SaaS software licenses

Membership fees

Monthly service plans

Subscription boxes

Key Features:

Predictable recurring revenue

Automatic invoice generation

Trial period support

Proration handling

METERED Billing Mode

METERED billing is for usage-based pricing where customers pay based on their actual consumption of services or resources.

Use Cases:

API usage billing

Cloud storage consumption

Utility services

Pay-per-use features

Key Features:

Flexible pricing based on usage

Custom invoice creation

Real-time usage tracking

Consumption-based charging

Implementation Guide

1. Setting Up Subscription Plans and Prices

For FIXED Billing Mode

Before creating FIXED billing subscriptions, you need to define your plans and pricing structure.

Create a Subscription Plan

Endpoint: POST /subscription-plans

{
  "name": "Premium Plan",
  "description": "Full access to all premium features",
  "metadata": {
    "features": ["unlimited_api_calls", "priority_support"]
  }
}

Create Prices for FIXED Billing

Endpoint: POST /subscription-plans/{planUid}/prices

{
  "amount": "2999",
  "currency": "NGN",
  "interval": "month",
  "intervalCount": 1,
  "trialPeriodDays": 14
}

For METERED Billing Mode

METERED billing does not require pre-created subscription plans or prices. Instead, you work directly with target pricing and create usage-based invoices as needed.

Metered subscriptions use:

Target Price: Specified during checkout session creation

Usage-based Invoices: Created when you need to charge for actual usage

Flexible Pricing: No fixed recurring schedule

2. Creating Subscription Checkout Sessions

FIXED Billing Checkout Session

Endpoint: POST /subscription-checkout-sessions

{
  "priceUid": "price_abc123",
  "billingMode": "FIXED",
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "successUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel"
}

METERED Billing Checkout Session

Endpoint: POST /subscription-checkout-sessions

{
  "billingMode": "METERED",
  "targetPrice": {
    "targetCurrency": "NGN",
    "targetAmount": "5000.00"
  },
  "customer": {
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "successUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel"
}

3. Customer Approval Flow

After creating a checkout session, you'll receive an approvalUrl in the response. Direct your customer to this URL where they will:

Approve the Smart Contract: The customer approves KuvarPay's smart contract to handle their subscription payments

Sign Authorization: The customer signs the EIP-712 authorization for the subscription

Automatic Confirmation: KuvarPay's frontend automatically confirms the session and redirects to your successUrl

Note: Businesses do not need to call the confirm endpoint directly. The KuvarPay frontend handles the confirmation process automatically after the customer completes the approval flow.

Checkout Session Response Example:

{
  "sessionUid": "session_abc123",
  "approvalUrl": "https://checkout.kuvarpay.com/approve/session_abc123",
  "status": "pending"
}

4. Managing Subscriptions

Retrieve Subscription Details

Endpoint: GET /subscriptions/{subscriptionUid}

Update Subscription

Endpoint: PATCH /subscriptions/{subscriptionUid}

{
  "status": "PAUSED",
  "cancel_at_period_end": true,
  "metadata": {
    "reason": "Customer requested pause"
  }
}

Cancel Subscription

Endpoint: DELETE /subscriptions/{subscriptionUid}

{
  "cancel_at_period_end": false,
  "reason": "Customer cancellation"
}

5. Invoice Management

FIXED Billing Invoices

For FIXED billing, invoices are automatically generated based on the subscription schedule. You can retrieve them using:

Endpoint: GET /subscriptions/{subscriptionUid}/invoices

METERED Billing Invoices

For METERED billing, you create invoices based on actual usage:

Endpoint: POST /subscriptions/{subscriptionUid}/invoices/metered

{
  "amount": "150.00",
  "currency": "NGN",
  "usage_description": "API calls for January 2024",
  "due_date": "2024-02-15T10:00:00Z",
  "charge_schedule": "scheduled",
  "metadata": {
    "period": "2024-01",
    "service": "api"
  }
}

Charge Scheduling Options:

immediate: Charge the invoice immediately upon creation

scheduled: Charge at the specified due_date (or 24 hours if not provided)

Examples:

Immediate Charging:

{
  "amount": "750.00",
  "currency": "NGN",
  "usage_description": "Premium API usage - urgent billing",
  "charge_schedule": "immediate"
}

Scheduled Charging:

{
  "amount": "2000.00",
  "currency": "NGN",
  "usage_description": "Monthly data processing usage",
  "due_date": "2024-02-01T09:00:00Z",
  "charge_schedule": "scheduled"
}

Charge Invoice

Endpoint: POST /subscription-invoices/{invoiceUid}/charge

{
  "amount": "15000",
  "currency": "NGN"
}

Webhook Events

KuvarPay sends webhook notifications for subscription events. Configure your webhook endpoint to handle these events:

Subscription Events

subscription.created - New subscription created

subscription.updated - Subscription details changed

subscription.cancelled - Subscription cancelled

subscription.activated - Subscription became active

subscription.trial_ended - Trial period ended

subscription.payment_failed - Payment attempt failed

Invoice Events

subscription_invoice.created - New invoice generated

subscription_invoice.paid - Invoice successfully paid

subscription_invoice.payment_failed - Invoice payment failed

Best Practices

For FIXED Billing

Trial Periods: Offer trial periods to reduce friction

Proration: Handle mid-cycle plan changes gracefully

Grace Periods: Implement grace periods for failed payments

Dunning Management: Set up retry logic for failed payments

For METERED Billing

Usage Tracking: Implement accurate usage measurement

Billing Cycles: Define clear billing periods

Usage Limits: Set reasonable usage caps to prevent bill shock

Real-time Monitoring: Provide usage dashboards for customers

General Best Practices

Webhook Handling: Implement idempotent webhook processing

Error Handling: Handle API errors gracefully

Security: Verify webhook signatures

Monitoring: Track subscription metrics and health

Customer Communication: Send clear notifications about billing events

Error Handling

Common error scenarios and how to handle them:

Payment Failures

Implement retry logic with exponential backoff

Send customer notifications

Provide payment method update flows

Subscription State Issues

Validate subscription status before operations

Handle concurrent modifications

Implement proper state transitions

Usage Tracking Errors (Metered)

Implement usage event deduplication

Handle late-arriving usage data

Provide usage correction mechanisms

Testing

Sandbox Mode

Use sandbox mode for testing:

All subscription operations work in sandbox

No real payments are processed

Use test webhook endpoints

Test Scenarios

Successful Subscription Flow

Payment Failures and Retries

Subscription Cancellations

Usage-based Billing (Metered)

Webhook Delivery and Processing

API Reference

For complete API documentation, refer to the OpenAPI specification at /openapi.yaml.

Key Endpoints

Endpoint	Method	Description
`/subscription-plans`	POST	Create subscription plan
`/subscription-plans/{planUid}`	GET	Get plan details
`/subscription-plans/{planUid}/prices`	POST	Create price for plan
`/subscription-checkout-sessions`	POST	Create checkout session
`/subscriptions/{subscriptionUid}`	GET	Get subscription
`/subscriptions/{subscriptionUid}`	PATCH	Update subscription
`/subscriptions/{subscriptionUid}`	DELETE	Cancel subscription
`/subscriptions/{subscriptionUid}/invoices`	GET	List invoices
`/subscriptions/{subscriptionUid}/invoices/metered`	POST	Create metered invoice
`/subscription-invoices/{invoiceUid}/charge`	POST	Charge invoice
`/subscription-currencies`	GET	List supported currencies

Support

For additional support:

Review the webhook documentation in webhooks.mdc

Check the OpenAPI specification for detailed endpoint documentation

Contact KuvarPay support for implementation assistance

Subscriptions Guide

KuvarPay Subscriptions Guide#

Overview#

Billing Modes#

FIXED Billing Mode#

METERED Billing Mode#

Implementation Guide#

1. Setting Up Subscription Plans and Prices#

For FIXED Billing Mode#

For METERED Billing Mode#

2. Creating Subscription Checkout Sessions#

FIXED Billing Checkout Session#

METERED Billing Checkout Session#

3. Customer Approval Flow#

4. Managing Subscriptions#

Retrieve Subscription Details#

Update Subscription#

Cancel Subscription#

5. Invoice Management#

FIXED Billing Invoices#

METERED Billing Invoices#

Charge Invoice#

Webhook Events#

Subscription Events#

Invoice Events#

Best Practices#

For FIXED Billing#

For METERED Billing#

General Best Practices#

Error Handling#

Payment Failures#

Subscription State Issues#

Usage Tracking Errors (Metered)#

Testing#

Sandbox Mode#

Test Scenarios#

API Reference#

Key Endpoints#

Support#