SNSP Payment API

Akzeptiere Zahlungen von Schnipp Schnapp GmbH Kunden in deinem Shop, deiner Website oder deinem Discord-Bot.

Übersicht

Die SNSP Payment API ermöglicht es dir, Zahlungen von Spielern zu akzeptieren, die ein Guthaben auf der Schnipp Schnapp GmbH haben. Das Geld wird sofort auf dein Bank-Konto gutgeschrieben.

Was du brauchst

• Einen Schnipp Schnapp GmbH Account
• Einen API-Key (erhältst du unter /payment-api/)
• Grundlegende Programmierkenntnisse (PHP, JavaScript, Python, etc.)

Schnellstart

In nur 3 Schritten zur ersten Zahlung:

1. API-Key holen

Gehe zu /payment-api/, logge dich ein und erstelle einen API-Key für deinen Shop.

2. Zahlung erstellen

POST /api/v1/payments
Authorization: Bearer sk_live_dein_api_key
Content-Type: application/json

{
  "amount": 9.99,
  "reference": "Bestellung-123",
  "redirect_url": "https://dein-shop.de/danke"
}

3. Kunde weiterleiten

Du erhältst eine checkout_url zurück. Leite den Kunden dorthin:

{
  "status": "success",
  "payment_id": "pay_abc123def456",
  "checkout_url": "https://snspgmbh.de/checkout/?payment_id=pay_abc123def456"
}

Das war's! Der Kunde bezahlt, und das Geld landet auf deinem Bank-Konto.

Authentifizierung

Alle API-Anfragen müssen mit deinem API-Key authentifiziert werden. Sende ihn im Authorization Header:

Authorization: Bearer sk_live_dein_api_key_hier

Fehlerbehandlung

Bei Fehlern gibt die API einen entsprechenden HTTP-Status-Code und eine Fehlermeldung zurück:

{
  "status": "error",
  "message": "Ungültiger API-Key"
}

Zahlung erstellen

POST /api/v1/payments
Authorization: Bearer sk_live_abc123...
Content-Type: application/json

{
  "amount": 29.99,
  "reference": "VIP-RANG-001",
  "description": "VIP Rang für 30 Tage",
  "redirect_url": "https://mein-shop.de/success?order=VIP-RANG-001"
}

{
  "status": "success",
  "payment_id": "pay_7f3a8b2c1d4e5f6a",
  "checkout_url": "https://snspgmbh.de/checkout/?payment_id=pay_7f3a8b2c1d4e5f6a",
  "amount": 29.99,
  "expires_at": 1703548800.0
}

Zahlung abfragen

{
  "status": "success",
  "payment": {
    "payment_id": "pay_7f3a8b2c1d4e5f6a",
    "amount": 29.99,
    "currency": "EUR",
    "status": "completed",
    "reference": "VIP-RANG-001",
    "description": "VIP Rang für 30 Tage",
    "payer_username": "Spieler123",
    "created_at": 1703462400.0,
    "completed_at": 1703462500.0
  }
}

Zahlung abbrechen

{
  "status": "success",
  "message": "Zahlung abgebrochen"
}

Zahlung erstatten

{
  "status": "success",
  "message": "Zahlung erstattet",
  "refunded_amount": 29.99
}

Zahlungsablauf

So läuft eine typische Zahlung ab:

Detaillierter Ablauf

1. Kunde klickt "Kaufen" in deinem Shop
2. Dein Server ruft POST /api/v1/payments auf
3. Du erhältst eine checkout_url
4. Du leitest den Kunden zu dieser URL weiter
5. Kunde loggt sich bei Schnipp Schnapp GmbH ein
6. Kunde bestätigt die Zahlung
7. Geld wird sofort auf dein Konto gutgeschrieben
8. Kunde wird zu deiner redirect_url weitergeleitet
9. Optional: Du prüfst den Status mit GET /api/v1/payments/{id}

Webhooks

Webhooks benachrichtigen deinen Server automatisch über Zahlungsereignisse. Du kannst eine Webhook-URL beim Erstellen deines API-Keys angeben.

Webhook-Ereignisse

Webhook-Payload

POST https://dein-server.de/webhook
Content-Type: application/json
X-GM-Timestamp: 1703462500
X-GM-Signature: sha256=abc123...

{
  "event": "payment.completed",
  "payment_id": "pay_7f3a8b2c1d4e5f6a",
  "amount": 29.99,
  "reference": "VIP-RANG-001",
  "payer_username": "Spieler123"
}

Signatur verifizieren

Um sicherzustellen, dass der Webhook wirklich von uns kommt, kannst du die Signatur prüfen:

// PHP Beispiel
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_GM_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_GM_SIGNATURE'];

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

if (hash_equals($expected, $signature)) {
    // Webhook ist authentisch
}

Code-Beispiele

<?php
// Konfiguration
$apiKey = "sk_live_DEIN_API_KEY";
$apiUrl = "https://api.primeoase.net";

// Zahlung erstellen
function createPayment($amount, $reference, $redirectUrl) {
    global $apiKey, $apiUrl;
    
    $data = [
        "amount" => $amount,
        "reference" => $reference,
        "redirect_url" => $redirectUrl
    ];
    
    $ch = curl_init("$apiUrl/api/v1/payments");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json"
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Beispiel: VIP-Rang verkaufen
$payment = createPayment(9.99, "VIP-" . uniqid(), "https://mein-shop.de/success");

if ($payment["status"] === "success") {
    // Kunde zur Bezahlseite weiterleiten
    header("Location: " . $payment["checkout_url"]);
    exit;
} else {
    die("Fehler: " . $payment["message"]);
}
?>

// Node.js / Server-side JavaScript
const API_KEY = "sk_live_DEIN_API_KEY";
const API_URL = "https://api.primeoase.net";

async function createPayment(amount, reference, redirectUrl) {
    const response = await fetch(`${API_URL}/api/v1/payments`, {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            amount,
            reference,
            redirect_url: redirectUrl
        })
    });
    
    return response.json();
}

// Beispiel: Express.js Route
app.post("/buy-vip", async (req, res) => {
    const payment = await createPayment(
        9.99,
        `VIP-${Date.now()}`,
        "https://mein-shop.de/success"
    );
    
    if (payment.status === "success") {
        res.redirect(payment.checkout_url);
    } else {
        res.status(400).send(payment.message);
    }
});

// Zahlungsstatus prüfen
async function checkPayment(paymentId) {
    const response = await fetch(`${API_URL}/api/v1/payments/${paymentId}`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    
    return response.json();
}

import requests

API_KEY = "sk_live_DEIN_API_KEY"
API_URL = "https://api.primeoase.net"

def create_payment(amount, reference, redirect_url):
    """Erstellt eine neue Zahlung"""
    response = requests.post(
        f"{API_URL}/api/v1/payments",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "amount": amount,
            "reference": reference,
            "redirect_url": redirect_url
        }
    )
    return response.json()

def check_payment(payment_id):
    """Prüft den Status einer Zahlung"""
    response = requests.get(
        f"{API_URL}/api/v1/payments/{payment_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return response.json()

# Beispiel: VIP-Rang verkaufen
payment = create_payment(
    amount=9.99,
    reference="VIP-12345",
    redirect_url="https://mein-shop.de/success"
)

if payment["status"] == "success":
    print(f"Checkout URL: {payment['checkout_url']}")
else:
    print(f"Fehler: {payment['message']}")

# Zahlung erstellen
curl -X POST https://api.primeoase.net/api/v1/payments \
  -H "Authorization: Bearer sk_live_DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9.99,
    "reference": "VIP-12345",
    "redirect_url": "https://mein-shop.de/success"
  }'

# Zahlung abfragen
curl https://api.primeoase.net/api/v1/payments/pay_abc123 \
  -H "Authorization: Bearer sk_live_DEIN_API_KEY"

# Zahlung abbrechen
curl -X POST https://api.primeoase.net/api/v1/payments/pay_abc123/cancel \
  -H "Authorization: Bearer sk_live_DEIN_API_KEY"

# Zahlung erstatten
curl -X POST https://api.primeoase.net/api/v1/payments/pay_abc123/refund \
  -H "Authorization: Bearer sk_live_DEIN_API_KEY"

Status-Codes

HTTP Status Codes

Limits

FAQ

Wie bekomme ich einen API-Key?

Gehe zu /payment-api/, logge dich mit deinem Schnipp Schnapp GmbH Account ein und erstelle einen neuen Shop. Du erhältst sofort deinen API-Key.

Wo landet das Geld?

Das Geld wird sofort auf dein Schnipp Schnapp GmbH Guthaben gutgeschrieben. Du kannst es von dort auf dein Schnipp Schnapp-Konto auszahlen.

Gibt es Gebühren?

Aktuell sind keine Gebühren für die Nutzung der Payment API vorgesehen.

Was passiert wenn der Kunde nicht genug Guthaben hat?

Der Kunde sieht auf der Checkout-Seite einen Hinweis, dass sein Guthaben nicht ausreicht, und einen Link zum Aufladen.

Kann ich Zahlungen stornieren?

Ausstehende Zahlungen (Status "pending") können jederzeit mit POST /api/v1/payments/{id}/cancel abgebrochen werden.

Kann ich Erstattungen durchführen?

Ja, mit POST /api/v1/payments/{id}/refund. Das Geld wird von deinem Konto abgezogen und dem Kunden gutgeschrieben. Du benötigst ausreichend Guthaben.

Was ist die redirect_url?

Die URL, zu der der Kunde nach erfolgreicher Zahlung weitergeleitet wird. Hier kannst du z.B. eine "Danke für deinen Kauf"-Seite anzeigen und die Bestellung abschließen.

Wie weiß ich, ob eine Zahlung erfolgreich war?

Du kannst entweder einen Webhook empfangen (automatisch) oder den Status jederzeit mit GET /api/v1/payments/{id} abfragen. Prüfe ob status gleich "completed" ist.

Mein API-Key wurde kompromittiert, was nun?

Gehe sofort zu /payment-api/ und klicke bei deinem Shop auf "Neuen Key". Der alte Key wird sofort ungültig.