Integration der 4Geeks Payments API in eine Node.js-Anwendung¶

Übersicht¶

4Geeks Payments ist eine Merchant of Record (MoR)-Plattform, die den gesamten Transaktionslebenszyklus abwickelt – von der Annahme von Zahlungen über die Verwaltung von Abonnements bis hin zur Steuerkonformität und Betrugsprävention. Dieses Tutorial zeigt Ihnen, wie Sie die 4Geeks Payments REST API in eine Node.js-Anwendung integrieren.

In diesem Tutorial werden Sie:

Richten Sie Ihr 4Geeks Payments-Konto ein und erhalten Sie API-Schlüssel
Erstellen Sie eine Gebühr (einmalige Zahlung)
Kunden anlegen und verwalten
Zahlungslinks generieren
Behandeln Sie Webhooks für Zahlungsereignisse
Rückerstattungen bearbeiten

Voraussetzungen¶

Ein aktiviertes 4Geeks Payments-Konto (Dienst aktivieren)
Node.js 18+ installiert
npm oder Garnpaketmanager
Grundlegendes Verständnis von REST APIs und Express.js

Schritt 1: Holen Sie sich Ihre API-Schlüssel¶

Melden Sie sich bei console.4geeks.io an.
Navigieren Sie zu Zahlungen → Einstellungen → API-Schlüssel
Klicken Sie auf „API-Schlüssel generieren“
Kopieren Sie Folgendes und bewahren Sie es sicher auf:
Öffentlicher Schlüssel (für clientseitige Vorgänge)
Geheimer Schlüssel (für serverseitige Vorgänge – diesen niemals preisgeben)

Wichtig: Verwenden Sie zum Testen Sandbox-Schlüssel. Wechseln Sie zu Produktionsschlüsseln, wenn Sie bereit sind, live zu gehen.

Schritt 2: Richten Sie Ihr Projekt ein¶

mkdir my-payment-app && cd my-payment-app
npm init -y
npm install express axios dotenv cors

Erstellen Sie Ihre Projektstruktur:

my-payment-app/
├── .env
├── server.js
├── routes/
│   └── payments.js
└── package.json

Schritt 3: Umgebungsvariablen konfigurieren¶

Erstellen Sie eine „.env“-Datei:

FOURGEEKS_PAYMENTS_SECRET_KEY=sk_test_your_secret_key_here
FOURGEEKS_PAYMENTS_PUBLIC_KEY=pk_test_your_public_key_here
FOURGEEKS_PAYMENTS_API_URL=https://api.4geeks.io/v1
PORT=3000

Schritt 4: Erstellen Sie den Express-Server¶

Erstellen Sie „server.js“:

require('dotenv').config();
const express = require('express');
const cors = require('cors');
const paymentRoutes = require('./routes/payments');

const app = express();

app.use(cors());
app.use(express.json());
app.use('/api/payments', paymentRoutes);

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Schritt 5: Zahlungswege erstellen¶

Erstellen Sie „routes/zahlungen.js“:

const express = require('express');
const axios = require('axios');
const router = express.Router();

const API_URL = process.env.FOURGEEKS_PAYMENTS_API_URL;
const SECRET_KEY = process.env.FOURGEEKS_PAYMENTS_SECRET_KEY;

const api = axios.create({
  baseURL: API_URL,
  headers: {
    'Authorization': `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
});

// Create a one-time charge
router.post('/charges', async (req, res) => {
  try {
    const { amount, currency, customer_id, description } = req.body;

    const response = await api.post('/charges', {
      amount,           // Amount in cents (e.g., 1000 = $10.00)
      currency,         // e.g., 'USD', 'EUR', 'CRC'
      customer_id,      // Existing customer ID or create new
      description,
      capture: true,    // Auto-capture the charge
    });

    res.json({ success: true, charge: response.data });
  } catch (error) {
    console.error('Charge error:', error.response?.data || error.message);
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create charge',
    });
  }
});

// Create a customer
router.post('/customers', async (req, res) => {
  try {
    const { email, name, phone, metadata } = req.body;

    const response = await api.post('/customers', {
      email,
      name,
      phone,
      metadata, // Optional: custom key-value pairs
    });

    res.json({ success: true, customer: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create customer',
    });
  }
});

// Generate a payment link
router.post('/payment-links', async (req, res) => {
  try {
    const { amount, currency, description, customer_email, success_url, cancel_url } = req.body;

    const response = await api.post('/payment-links', {
      amount,
      currency,
      description,
      customer_email,
      success_url,    // Redirect after successful payment
      cancel_url,     // Redirect if customer cancels
    });

    res.json({ success: true, payment_link: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create payment link',
    });
  }
});

// Process a refund
router.post('/charges/:charge_id/refund', async (req, res) => {
  try {
    const { charge_id } = req.params;
    const { amount, reason } = req.body;

    const response = await api.post(`/charges/${charge_id}/refunds`, {
      amount,  // Optional: partial refund (in cents). Omit for full refund
      reason,  // e.g., 'duplicate', 'fraudulent', 'requested_by_customer'
    });

    res.json({ success: true, refund: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to process refund',
    });
  }
});

// Get charge details
router.get('/charges/:charge_id', async (req, res) => {
  try {
    const { charge_id } = req.params;
    const response = await api.get(`/charges/${charge_id}`);
    res.json({ success: true, charge: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to get charge',
    });
  }
});

module.exports = router;

Schritt 6: Webhooks verarbeiten¶

Webhooks benachrichtigen Ihren Server über Zahlungsereignisse (erfolgreiche Abbuchungen, fehlgeschlagene Zahlungen, Rückerstattungen usw.).

Zu „server.js“ hinzufügen:

// Webhook endpoint
app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-4geeks-signature'];
  const payload = req.body;

  // Verify webhook signature (implement verification logic)
  // const isValid = verifyWebhookSignature(payload, signature);
  // if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'charge.succeeded':
      console.log('Payment successful:', event.data.charge_id);
      // Update order status, send confirmation email, etc.
      break;
    case 'charge.failed':
      console.log('Payment failed:', event.data.charge_id);
      // Notify customer, retry logic, etc.
      break;
    case 'refund.completed':
      console.log('Refund processed:', event.data.refund_id);
      // Update order status, notify customer, etc.
      break;
    case 'subscription.created':
      console.log('New subscription:', event.data.subscription_id);
      // Activate subscription, send welcome email, etc.
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.json({ received: true });
});

Schritt 7: Testen Sie Ihre Integration¶

Starten Sie den Server:

node server.js

Test mit Curl:

# Create a customer
curl -X POST http://localhost:3000/api/payments/customers \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "name": "John Doe"}'

# Create a charge
curl -X POST http://localhost:3000/api/payments/charges \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD", "customer_id": "cus_xxx", "description": "Test charge"}'

# Generate a payment link
curl -X POST http://localhost:3000/api/payments/payment-links \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "currency": "USD", "description": "Premium Plan", "success_url": "https://yoursite.com/success", "cancel_url": "https://yoursite.com/cancel"}'

Karten testen¶

Verwenden Sie diese Testkarten im Sandbox-Modus:

Kartennummer	Ergebnis
4242 4242 4242 4242	Erfolgreiche Zahlung
4000 0000 0000 9995	Abgelehnt (unzureichende Mittel)
4000 0000 0000 0002	Erfordert 3D Secure-Authentifizierung
4000 0000 0000 0010	Erfordert CVC-Überprüfung

Best Practices¶

Sicherheit¶

Legen Sie niemals Ihren geheimen Schlüssel im clientseitigen Code offen
Umgebungsvariablen verwenden für alle Anmeldeinformationen
Überprüfen Sie Webhook-Signaturen, um gefälschte Ereignisse zu verhindern
Idempotenzschlüssel implementieren für die Ladungserstellung, um Duplikate zu verhindern

Fehlerbehandlung¶

Überprüfen Sie immer „error.response?.data“ auf detaillierte Fehlermeldungen – Implementieren Sie eine Wiederholungslogik für vorübergehende Fehler
Protokollieren Sie alle Zahlungsereignisse zur Prüfung
Behandeln Sie 3D Secure-Weiterleitungen ordnungsgemäß

Compliance¶

4Geeks Payments ist PCI DSS-kompatibel – Kartendaten berühren niemals Ihre Server
Steuerkonformität wird automatisch gehandhabt (Mehrwertsteuer, Umsatzsteuer, GST)
Als eingetragener Händler übernimmt 4Geeks die Haftung für Rückbuchungen

Was kommt als nächstes?¶

Erfahren Sie mehr über Wiederkehrende Abonnementabrechnung
Entdecken Sie 3D Secure Implementation
Lesen Sie mehr über Multi-Currency Checkout
Sehen Sie sich die vollständige [API-Referenz] an (https://docs.4geeks.io/en/api/)

Brauchen Sie Hilfe?¶

Dokumentation: docs.4geeks.io/en/zahlungen
API-Referenz: docs.4geeks.io/en/api
Discord: Discord
Support: Verfügbar über das Konsolen-Dashboard

Noch Fragen? Get support or explore tutorials