API Reference

Base URL

https://api.pingbacks.io

All endpoints return JSON. Use Content-Type: application/json for POST/PUT requests.

Core Concept: Ping-ID

Every registered customer receives a unique Ping-ID (format: PB-XXXXXXXXXXXX). This is their loyalty card number — they enter it during checkout, and you send it with your API calls. No need to collect or store email addresses.

// Customer enters Ping-ID at checkout
POST /api/v1/earn
{ "ping_id": "PB-A3F8K2M9X", ... }

// Fallback for legacy integrations
POST /api/v1/earn
{ "customer_email": "kunde@example.de", ... }

Earning Points

curl -X POST https://api.pingbacks.io/api/v1/earn \
  -H "Content-Type: application/json" \
  -H "X-PingBacks-API-Key: pb_live_8f391a..." \
  -d '{
    "ping_id": "PB-A3F8K2M9X",
    "tenant_customer_id": "cust_12345",
    "invoice_id": "inv_99812",
    "items": [
      { "category": "hosting", "amount_eur": 49.90 },
      { "category": "domain",  "amount_eur": 14.90 }
    ]
  }'

{
  "status": "success",
  "pingbacks_user_id": "8040dd4c-6929-4741-8fd6-69386c308d2f",
  "points_earned": 648,
  "new_global_balance": 12850
}

Query Balance

curl "https://api.pingbacks.io/api/v1/balance?ping_id=PB-A3F8K2M9X" \
  -H "X-PingBacks-API-Key: pb_live_8f391a..."

{
  "customer_email": "developer@agency-xyz.de",
  "ping_id": "PB-A3F8K2M9X",
  "global_balance": 12850,
  "status": "linked"
}

Redeeming Points

curl -X POST https://api.pingbacks.io/api/v1/redeem/invoice \
  -H "Content-Type: application/json" \
  -H "X-PingBacks-API-Key: pb_live_8f391a..." \
  -d '{
    "ping_id": "PB-A3F8K2M9X",
    "points_to_redeem": 1000,
    "invoice_id": "inv_99850"
  }'

{
  "status": "success",
  "points_redeemed": 1000,
  "equivalent_value_eur": 10.00,
  "remaining_global_balance": 11850
}

Webhooks

POST <your-webhook-url>
Content-Type: application/json
X-PingBacks-Signature: <HMAC-SHA256-hex>

{
  "event": "points_redeemed",
  "tenant_id": "5927c0df-0284-4f27-ba49-6b1264b788b4",
  "user_id": "1bebdfc0-2f3f-4233-a66c-706e8cb41060",
  "reference_id": "inv_99850",
  "points": 1000,
  "timestamp": "2026-07-25T12:00:00Z",
  "signature": "a1b2c3d4e5f6..."
}

// Node.js
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const payload = { event: body.event, tenant_id: body.tenant_id,
    user_id: body.user_id, reference_id: body.reference_id,
    points: body.points, timestamp: body.timestamp };
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

// PHP
function verifyWebhook($body, $signature, $secret) {
    $payload = json_encode([
        'event'        => $body['event'],
        'tenant_id'    => $body['tenant_id'],
        'user_id'      => $body['user_id'],
        'reference_id' => $body['reference_id'],
        'points'       => $body['points'],
        'timestamp'    => $body['timestamp'],
    ]);
    return hash_equals(
        hash_hmac('sha256', $payload, $secret),
        $signature
    );
}

Auth API

JWT-based authentication for provider dashboards and customer portals. All auth endpoints are public (no API key required).

// Request
{
  "company_name": "ServerBlitz GmbH",
  "contact_email": "kontakt@serverblitz.de",
  "contact_name": "Max Mustermann",
  "admin_email": "admin@serverblitz.de",
  "admin_password": "secure1234",
  "webhook_url": "https://serverblitz.de/webhooks/pingbacks"
}

// Response 201 Created
{
  "status": "success",
  "message": "Registration submitted. Awaiting admin approval.",
  "tenant_id": "5927c0df-..."
}

// Request
{ "email": "developer@agency-xyz.de", "password": "secure1234" }

// Response 201 Created
{
  "status": "success",
  "token": "eyJhbGciOi...",
  "user": {
    "id": "1bebdfc0-...",
    "email": "developer@agency-xyz.de",
    "current_balance": 0,
    "ping_id": "PB-A3F8K2M9X"
  }
}

// Response 200 OK
{
  "status": "success",
  "token": "eyJhbGciOi...",
  "user": {
    "email": "admin@serverblitz.de",
    "tenantId": "5927c0df-...",
    "tenantName": "ServerBlitz GmbH",
    "role": "admin"
  }
}

// Response 200 OK
{
  "status": "success",
  "token": "eyJhbGciOi...",
  "user": {
    "email": "developer@agency-xyz.de",
    "current_balance": 12850,
    "ping_id": "PB-A3F8K2M9X"
  }
}

Dashboard API JWT Required

Authenticated endpoints for provider dashboards. All require Authorization: Bearer <token>.

Error Codes

All errors follow a consistent format: { "status": "error", "code": "ERROR_CODE", "message": "Human-readable description" }

PHP SDK

Minimal, zero-dependency client for PHP 7.4+. Works with WHMCS, WordPress, WooCommerce, and any custom CMS.

<?php
require_once 'PingBacksClient.php';

$client = new PingBacksClient('pb_live_8f391a...', 'https://api.pingbacks.io');

// 1. Credit points after payment
$result = $client->earn(
    pingId: 'PB-A3F8K2M9X',
    tenantCustomerId: 'cust_12345',
    invoiceId: 'inv_99812',
    items: [
        ['category' => 'hosting', 'amount_eur' => 49.90],
        ['category' => 'domain',  'amount_eur' => 14.90],
    ]
);
echo "Earned: {$result['points_earned']} points\n";

// 2. Check balance
$balance = $client->getBalance(pingId: 'PB-A3F8K2M9X');
echo "Balance: {$balance['global_balance']} points\n";

// 3. Redeem points
$redeem = $client->redeemInvoice(
    pingId: 'PB-A3F8K2M9X',
    pointsToRedeem: 500,
    invoiceId: 'inv_789'
);
echo "Redeemed: {$redeem['points_redeemed']}\n";
echo "Remaining: {$redeem['remaining_global_balance']}\n";

Full SDK source and example script: github.com/Host-On/pingbacks/sdk/php