Mernphis - Subscription OS for Mobile-Money Markets

Overview

The Mernphis API allows you to programmatically manage customers, services, and subscriptions. This is perfect for integrating Mernphis with your existing mobile apps, web applications, or custom systems.

RESTful API

Simple HTTP requests with JSON responses

Secure

API key authentication with HTTPS

Real-time

Instant updates and webhooks

Base URL

https://api.mernphis.com/api/v1

Authentication

All API requests require an API key. You can generate API keys from your Mernphis dashboard (Settings → API Keys).

Headers

Include your API key in one of two ways:

Authorization: Bearer mph_your_api_key_here

Note: API keys start with mph_ prefix. Keep your API keys secure and never expose them in client-side code.

Services API

Services are subscription plan templates that you offer to customers.

GET/api/v1/services

Retrieve all active services for your organization.

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "name": "Premium Plan",
      "slug": "premium-plan",
      "description": "Full access to all features",
      "amount": 25.00,
      "currency": "USD",
      "billing_type": "monthly",
      "trial_days": 7,
      "grace_period_days": 3,
      "is_active": true,
      "is_featured": true,
      "features": ["Feature 1", "Feature 2"],
      "metadata": {},
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

POST/api/v1/services

Create a new service template.

Request Body:

{
  "name": "Premium Plan",
  "description": "Full access to all features",
  "amount": 25.00,
  "currency": "USD",
  "billing_type": "monthly",
  "trial_days": 7,
  "grace_period_days": 3,
  "features": ["Feature 1", "Feature 2"]
}

Required Fields:

• name (string)
• amount (number)
• billing_type (string: "monthly", "quarterly", "annual")

Response:

{
  "success": true,
  "data": { /* service object */ },
  "message": "Service created successfully"
}

Customers API

Customers are your end-users who subscribe to your services.

GET/api/v1/customers

Retrieve customers with pagination.

Query Parameters:

• limit (optional): Number of customers to return (default: 100)
• offset (optional): Pagination offset (default: 0)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "country": "United States",
      "currency": "USD",
      "external_id": "USER-123",
      "metadata": {
        "notes": "VIP customer",
        "tags": ["premium", "early-adopter"]
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

POST/api/v1/customers

Create a new customer.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "country": "United States",
  "currency": "USD",
  "external_id": "USER-123",
  "metadata": {
    "notes": "VIP customer",
    "tags": ["premium"]
  }
}

Required Fields:

• name (string)

Optional Fields:

• email (string)
• phone (string)
• external_id (string): Your app's user ID
• metadata (object): Custom data

Subscriptions API

Subscriptions link customers to services with billing details.

GET/api/v1/subscriptions

Retrieve subscriptions with filtering options.

Query Parameters:

• customer_id (optional): Filter by customer
• service_id (optional): Filter by service
• status (optional): Filter by status
• limit (optional): Number to return (default: 100)
• offset (optional): Pagination offset (default: 0)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "customer_id": "uuid",
      "service_id": "uuid",
      "plan_name": "Premium Plan",
      "plan_type": "monthly",
      "amount": 25.00,
      "currency": "USD",
      "payment_method": "manual",
      "status": "active",
      "billing_cycle_start": "2025-01-01T00:00:00Z",
      "billing_cycle_end": "2025-02-01T00:00:00Z",
      "next_billing_date": "2025-02-01T00:00:00Z",
      "metadata": { "grace_period_days": 3 },
      "customers": { "name": "John Doe" },
      "services": { "name": "Premium Plan" }
    }
  ],
  "count": 1
}

POST/api/v1/subscriptions

Create a new subscription (service-based or custom).

Link customer to an existing service. Service details are auto-filled.

{
  "customer_id": "uuid",
  "service_id": "uuid",
  "payment_method": "manual",
  "status": "active"
}

Payment Methods:

manualselcomazampaystripe

Error Handling

All errors follow a consistent JSON format:

{
  "error": "Error message description"
}

HTTP Status Codes

400

Bad Request

Missing or invalid parameters

401

Unauthorized

Invalid or missing API key

404

Not Found

Resource doesn't exist

409

Conflict

Resource already exists (e.g., duplicate email)

500

Internal Server Error

Server-side error

Common Use Cases

1. Onboard User from Your Mobile App

When a user signs up in your app, create them as a customer in Mernphis:

// Step 1: Create customer
const customerResponse = await fetch('https://api.mernphis.com/api/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mph_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: user.name,
    email: user.email,
    external_id: user.id, // Your app's user ID
    country: user.country,
    currency: user.preferredCurrency
  })
}).then(res => res.json())

// Step 2: Subscribe to service
const subscriptionResponse = await fetch('https://api.mernphis.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mph_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: customerResponse.data.id,
    service_id: 'premium-plan-service-id',
    payment_method: 'selcom',
    status: 'trialing' // Start with trial
  })
}).then(res => res.json())

2. Check Customer's Subscription Status

Query subscriptions by your app's user ID:

// Get customer by external_id
const customersResponse = await fetch(
  'https://api.mernphis.com/api/v1/customers',
  {
    headers: { 'Authorization': 'Bearer mph_your_api_key' }
  }
).then(res => res.json())
const customer = customersResponse.data.find(c => c.external_id === yourUserId)

// Get their subscriptions
const subscriptionsResponse = await fetch(
  `https://api.mernphis.com/api/v1/subscriptions?customer_id=${customer.id}`,
  {
    headers: { 'Authorization': 'Bearer mph_your_api_key' }
  }
).then(res => res.json())

const hasActiveSubscription = subscriptionsResponse.data.some(
  sub => sub.status === 'active' || sub.status === 'trialing'
)

3. Sync Your Existing Users

Bulk import your existing users:

for (const user of existingUsers) {
  await fetch('https://api.mernphis.com/api/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mph_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: user.name,
      email: user.email,
      external_id: user.id,
      metadata: {
        imported_from: 'legacy_system',
        imported_at: new Date().toISOString()
      }
    })
  })
}

Rate Limits

API rate limits are based on your subscription plan:

Free Plan

100

requests per minute

Starter Plan

500

requests per minute

Pro Plan

2,000

requests per minute

Enterprise

Custom

Contact sales for custom limits

Note: Exceeded rate limits return 429 Too Many Requests status.

SDKs & Libraries

Official SDKs to simplify integration with your favorite languages.

Node.js / JavaScript

Coming Soon

npm install @mernphis/sdk

import { Mernphis } from '@mernphis/sdk'

const mernphis = new Mernphis('mph_your_api_key')

// Create customer
const customer = await mernphis.customers.create({
  name: 'John Doe',
  email: 'john@example.com'
})

// Create subscription
const subscription = await mernphis.subscriptions.create({
  customerId: customer.id,
  serviceId: 'service-id'
})

Python

Coming Soon

pip install mernphis

from mernphis import Mernphis

client = Mernphis('mph_your_api_key')

# Create customer
customer = client.customers.create(
    name='John Doe',
    email='john@example.com'
)

# Create subscription
subscription = client.subscriptions.create(
    customer_id=customer.id,
    service_id='service-id'
)

Need Help?

Documentation

Comprehensive guides and tutorials

View Docs

API Status

Check current system status

View Status

API Reference

Overview

RESTful API

Secure

Real-time

Authentication

Headers

Services API

Customers API

Subscriptions API

Error Handling

HTTP Status Codes

Common Use Cases

1. Onboard User from Your Mobile App

2. Check Customer's Subscription Status

3. Sync Your Existing Users

Rate Limits

Free Plan

Starter Plan

Pro Plan

Enterprise

SDKs & Libraries

Node.js / JavaScript

Python

Need Help?

Documentation

API Status