🚀 LogeePay API

Complete API documentation for subscription and payment management

Introduction

Welcome to the LogeePay API! This RESTful API allows you to manage customers, subscriptions, payments, and credits programmatically.

Base URL

https://pay.logee.fr/api

Response Format

All responses are returned in JSON format with the following structure:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Authentication

The LogeePay API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Obtaining an API Key

API keys are generated when creating an app in the admin dashboard. Each app has a unique API key.

Using Your API Key

curl https://pay.logee.fr/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Security Note: Keep your API keys secure! Never expose them in client-side code or public repositories.

Customers

Manage customer records and link them to your application.

Create or Get Customer

POST /api/customers

Create a new customer or retrieve existing one by email.

Request Body

{
  "email": "user@example.com",
  "name": "John Doe"
}

Example

curl -X POST https://pay.logee.fr/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe"
  }'

Response

{
  "success": true,
  "message": "Customer retrieved",
  "data": {
    "customer": {
      "id": 1,
      "email": "user@example.com",
      "name": "John Doe",
      "created_at": "2024-02-07T10:30:00Z"
    }
  }
}

Get Customer by ID

GET /api/customers/{id}

Retrieve customer details by ID.

Example

curl https://pay.logee.fr/api/customers/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Customer by Email

GET /api/customers/email/{email}

Lookup customer by email address.

Example

curl https://pay.logee.fr/api/customers/email/user@example.com \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Customer

PUT /api/customers/{id}

Update customer information.

Request Body

{
  "name": "Jane Doe",
  "metadata": {
    "company": "Acme Inc"
  }
}

Example

curl -X PUT https://pay.logee.fr/api/customers/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe"}'

Link Customer to App

POST /api/customers/{id}/link

Link customer to your application with an optional external user ID.

Request Body

{
  "external_user_id": "your-app-user-123"
}

Example

curl -X POST https://pay.logee.fr/api/customers/1/link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "user-123"}'

Get Customer's Plan

GET /api/customers/{id}/plan

Get the customer's current subscription plan.

Example

curl https://pay.logee.fr/api/customers/1/plan \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Plan retrieved",
  "data": {
    "plan": {
      "id": 2,
      "name": "Pro Plan",
      "slug": "pro",
      "price": 2900,
      "currency": "EUR",
      "interval": "month",
      "features": {
        "credits_per_month": 1000,
        "api_calls_limit": 10000
      }
    }
  }
}

Plans

Retrieve available subscription plans.

List Active Plans

GET /api/plans

Get all active subscription plans.

Example

curl https://pay.logee.fr/api/plans \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Plans retrieved",
  "data": {
    "plans": [
      {
        "id": 1,
        "name": "Starter",
        "slug": "starter",
        "price": 990,
        "currency": "EUR",
        "interval": "month",
        "stripe_price_id": "price_xxx",
        "features": {
          "credits_per_month": 100
        },
        "is_active": true
      },
      {
        "id": 2,
        "name": "Pro",
        "slug": "pro",
        "price": 2900,
        "currency": "EUR",
        "interval": "month",
        "stripe_price_id": "price_yyy",
        "features": {
          "credits_per_month": 1000
        },
        "is_active": true
      }
    ]
  }
}

Checkout

Create Stripe checkout sessions for subscription purchases.

Create Checkout Session

POST /api/checkout

Create a Stripe checkout session for a customer to subscribe to a plan.

Request Body

{
  "customer_id": 1,
  "plan_id": 2,
  "success_url": "https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://yourapp.com/cancel"
}

Example

curl -X POST https://pay.logee.fr/api/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 1,
    "plan_id": 2,
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel"
  }'

Response

{
  "success": true,
  "message": "Checkout session created",
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_xxx",
    "session_id": "cs_test_xxx"
  }
}
Note: Redirect the customer to the checkout_url to complete payment.

Subscriptions

Manage customer subscriptions.

Get Customer Subscriptions

GET /api/customers/{id}/subscriptions

Get all subscriptions for a customer.

Example

curl https://pay.logee.fr/api/customers/1/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Subscriptions retrieved",
  "data": {
    "subscriptions": [
      {
        "id": 1,
        "customer_id": 1,
        "plan_id": 2,
        "stripe_subscription_id": "sub_xxx",
        "status": "active",
        "current_period_start": "2024-02-01T00:00:00Z",
        "current_period_end": "2024-03-01T00:00:00Z",
        "cancel_at_period_end": false,
        "created_at": "2024-02-01T00:00:00Z"
      }
    ]
  }
}

Cancel Subscription

POST /api/subscriptions/{id}/cancel

Cancel a subscription at the end of the current billing period.

Example

curl -X POST https://pay.logee.fr/api/subscriptions/1/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Subscription cancelled successfully",
  "data": {
    "subscription": {
      "id": 1,
      "status": "active",
      "cancel_at_period_end": true,
      "current_period_end": "2024-03-01T00:00:00Z"
    }
  }
}

Credits

Manage customer credit balances.

Get Credit Balance

GET /api/customers/{id}/credits

Get the current credit balance for a customer.

Example

curl https://pay.logee.fr/api/customers/1/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Credit balance retrieved",
  "data": {
    "balance": 850,
    "customer_id": 1
  }
}

Add Credits

POST /api/customers/{id}/credits/add

Add credits to a customer's balance.

Request Body

{
  "amount": 100,
  "reason": "Monthly renewal",
  "reference": "renewal-2024-02"
}

Example

curl -X POST https://pay.logee.fr/api/customers/1/credits/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "reason": "Bonus credits"
  }'

Deduct Credits

POST /api/customers/{id}/credits/deduct

Deduct credits from a customer's balance.

Request Body

{
  "amount": 10,
  "reason": "API call usage",
  "reference": "api-call-12345"
}

Example

curl -X POST https://pay.logee.fr/api/customers/1/credits/deduct \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "reason": "API usage"
  }'

Response

{
  "success": true,
  "message": "Credits deducted successfully",
  "data": {
    "balance": 840,
    "deducted": 10
  }
}
Important: Deducting credits will fail if the customer has insufficient balance. Check balance before deducting.

Webhooks

LogeePay sends webhook notifications to your app when important events occur.

Events

Your app will receive notifications for the following events:

Event Description
subscription.created A new subscription was created
subscription.updated Subscription details changed
subscription.cancelled Subscription was cancelled
payment.succeeded Payment was successful
payment.failed Payment failed
credits.added Credits were added to balance
credits.deducted Credits were deducted from balance
credits.depleted Customer ran out of credits

Webhook Payload

{
  "event": "subscription.created",
  "timestamp": "2024-02-07T10:30:00Z",
  "data": {
    "subscription_id": 1,
    "customer_id": 1,
    "customer_email": "user@example.com",
    "plan_id": 2,
    "plan_name": "Pro",
    "status": "active"
  }
}

Verifying Webhooks

All webhooks are signed with HMAC-SHA256. Verify the signature to ensure the request is authentic.

Headers

  • X-Webhook-Signature - HMAC-SHA256 signature
  • X-Webhook-Timestamp - Unix timestamp

Verification Example (PHP)

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Prevent replay attacks (5 min window)
if (abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit('Request too old');
}

// Process webhook
$event = json_decode($payload, true);
Best Practice: Always return a 200 status code quickly, then process webhooks asynchronously.

Error Codes

The API uses standard HTTP status codes and returns detailed error messages.

HTTP Status Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden Access denied
404 Not Found Resource not found
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred
503 Service Unavailable Service temporarily unavailable

Error Response Format

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["Email address is required"],
    "name": ["Name must be at least 2 characters"]
  }
}

Common Error Messages

Message Solution
Invalid API key Check your Authorization header
Customer not found Verify the customer ID exists
Insufficient credits Customer needs more credits
Plan not active Choose an active subscription plan
Invalid email address Provide a valid email format

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits.

Current Limits

Limit Type Rate
Requests per minute 60 requests
Requests per hour 1,000 requests
Burst requests 10 requests/second

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1612704000
Header Description
X-RateLimit-Limit Maximum requests allowed per window
X-RateLimit-Remaining Requests remaining in current window
X-RateLimit-Reset Unix timestamp when the limit resets

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "success": false,
  "message": "Rate limit exceeded",
  "retry_after": 45
}
Best Practice: Implement exponential backoff when receiving 429 responses. Use the retry_after value to determine when to retry.

Support

Need help? Contact us at admin@logee.fr

LogeePay API v1.0 • Last updated: February 2024