API Dokumentation

Die PaymentHub API ermöglicht es dir, Members programmatisch zu verwalten, Subscriptions zu steuern und Custom Metadata für deine Integration zu speichern.
Base URL
https://api.paymenthub.com/v1
Rate Limits
  • 1000 requests per hour per API key
  • Burst: 100 requests per minute
  • Headers zeigen verbleibende Limits: X-RateLimit-Remaining

Authentication

Alle API Requests müssen mit einem Bearer Token authentifiziert werden.

Header Authorization 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.paymenthub.com/v1/members

Members

GET /members
List all members

Gibt eine paginierte Liste aller Members zurück.

Query Parameters
Parameter Type Description
page integer Page number (default: 1)
limit integer Items per page (default: 20, max: 100)
status string Filter by status: active, trial, canceled
plan_id string Filter by plan ID
Example Request
curl -X GET https://api.paymenthub.com/v1/members?status=active&limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response
{
  "members": [
    {
      "id": "mem_1234567890",
      "email": "user@example.com",
      "name": "Max Mustermann",
      "plan_id": "plan_premium",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "metadata": {
        "discord_id": "123456789",
        "custom_field": "value"
      }
    }
  ],
  "pagination": {
    "total": 156,
    "page": 1,
    "per_page": 10,
    "total_pages": 16
  }
}
POST /members
Create a member

Erstellt einen neuen Member mit optionaler Metadata.

Request Body
{
  "email": "user@example.com",
  "name": "Max Mustermann",
  "plan_id": "plan_premium",
  "trial_days": 7,
  "metadata": {
    "discord_id": "123456789",
    "minecraft_uuid": "abc-def-ghi",
    "server_roles": ["vip", "beta_tester"],
    "custom_data": {
      "level": 1,
      "points": 0
    }
  }
}
Response
{
  "id": "mem_1234567890",
  "email": "user@example.com",
  "name": "Max Mustermann",
  "plan_id": "plan_premium",
  "status": "trial",
  "trial_ends_at": "2024-01-22T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "discord_id": "123456789",
    "minecraft_uuid": "abc-def-ghi",
    "server_roles": ["vip", "beta_tester"],
    "custom_data": {
      "level": 1,
      "points": 0
    }
  },
  "subscription": {
    "id": "sub_abc123",
    "status": "trialing",
    "next_payment": "2024-01-22T10:30:00Z"
  }
}
PATCH /members/{member_id}
Update member metadata

Aktualisiert die Metadata eines Members. Besonders nützlich für Server-Owner.

Use Cases für Server Owner
  • Spieler-Level und Achievements speichern
  • Discord Rollen synchronisieren
  • In-Game Währung und Items tracken
  • Custom Permissions verwalten
Request Body
{
  "metadata": {
    "discord_roles": ["premium", "og_member"],
    "game_stats": {
      "level": 42,
      "experience": 15000,
      "achievements": ["first_purchase", "year_member", "top_contributor"],
      "inventory": {
        "coins": 5000,
        "premium_items": ["sword_legendary", "mount_dragon"]
      }
    },
    "server_access": {
      "survival": true,
      "creative": true,
      "skyblock": false,
      "special_events": true
    },
    "last_active": "2024-01-15T10:30:00Z",
    "total_playtime_hours": 250
  }
}

Metadata System

Was ist Metadata?

Metadata erlaubt es dir, beliebige strukturierte Daten zu jedem Member zu speichern. Perfekt für Gaming-Server, Discord Communities und Custom Integrationen.

Pro Tipp: Du kannst bis zu 16KB JSON Data pro Member speichern!
Beispiele für Server Owner
Minecraft Server
{
  "minecraft": {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "rank": "vip",
    "homes": ["spawn", "shop", "base"],
    "balance": 10000,
    "playtime": 4320,
    "last_seen": "2024-01-15"
  }
}
Discord Bot
{
  "discord": {
    "user_id": "123456789012345678",
    "roles": ["premium", "verified"],
    "level": 25,
    "xp": 12500,
    "voice_minutes": 3600,
    "messages_sent": 1500
  }
}
FiveM Server
{
  "fivem": {
    "steam_id": "steam:110000132c6b978",
    "character": {
      "name": "John Doe",
      "job": "police",
      "bank": 50000,
      "inventory": []
    },
    "whitelist": true,
    "priority": 10
  }
}
Game Server Network
{
  "network": {
    "total_score": 5000,
    "unlocked_servers": [
      "survival", "creative", "pvp"
    ],
    "cosmetics": ["hat_crown", "pet_dragon"],
    "friend_list": ["user123", "user456"],
    "clan": "elite_warriors"
  }
}

Webhooks

Event Types

Erhalte Real-time Notifications wenn wichtige Events passieren.

Event Description Payload
member.created Neuer Member registriert Member object
member.updated Member Daten aktualisiert Member object + changes
member.deleted Member gelöscht/gekündigt Member ID + reason
subscription.created Neue Subscription gestartet Subscription object
subscription.renewed Subscription verlängert Subscription object
subscription.canceled Subscription gekündigt Subscription object + reason
payment.succeeded Zahlung erfolgreich Payment object
payment.failed Zahlung fehlgeschlagen Payment object + error
Webhook Payload Example
{
  "id": "evt_1234567890",
  "type": "member.created",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "member": {
      "id": "mem_abc123",
      "email": "user@example.com",
      "plan_id": "plan_premium",
      "metadata": {
        "discord_id": "123456789"
      }
    }
  }
}
Webhook Security

Alle Webhooks werden mit einem Signature Header gesendet:

X-PaymentHub-Signature: sha256=HMAC_SIGNATURE

Verifiziere die Signature mit deinem Webhook Secret:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = 'sha256=' + hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Error Handling

Error Response Format
{
  "error": {
    "type": "invalid_request_error",
    "message": "The email field is required",
    "code": "parameter_missing",
    "param": "email",
    "request_id": "req_abc123"
  }
}
HTTP Status Codes
Code Description
200 Request erfolgreich
201 Resource erstellt
400 Bad Request - Fehlerhafte Parameter
401 Unauthorized - API Key fehlt oder ungültig
403 Forbidden - Keine Berechtigung
404 Not Found - Resource nicht gefunden
429 Too Many Requests - Rate Limit erreicht
500 Internal Server Error

SDK & Libraries

Node.js
npm install @paymenthub/node
const PaymentHub = require('@paymenthub/node');
const client = new PaymentHub('YOUR_API_KEY');

// Create member with metadata
const member = await client.members.create({
  email: 'user@example.com',
  plan_id: 'plan_premium',
  metadata: {
    discord_id: '123456789'
  }
});

// Update metadata
await client.members.updateMetadata(member.id, {
  level: 50,
  achievements: ['first_purchase']
});
Python
pip install paymenthub
import paymenthub

client = paymenthub.Client('YOUR_API_KEY')

# Create member with metadata
member = client.members.create(
    email='user@example.com',
    plan_id='plan_premium',
    metadata={
        'discord_id': '123456789'
    }
)

# Update metadata
client.members.update_metadata(
    member.id,
    {
        'level': 50,
        'achievements': ['first_purchase']
    }
)