Zum Inhalt

So akzeptieren Sie Kreditkartenzahlungen auf Ihrer Website mit der 4Geeks Payments API

🤖 Erklären mit KI

Die 4Geeks Payments API ermöglicht es Entwicklern, vollständig anpassbare Checkout-Erlebnisse zu erstellen. Egal, ob Sie einen einfachen E-Commerce-Shop oder eine komplexe SaaS-Plattform betreiben, mit dieser API können Sie Kreditkarten, Debitkarten und Transaktionen mit digitalen Geldbörsen direkt aus Ihrer Anwendung heraus verarbeiten.

Dieser Leitfaden bietet eine schrittweise Anleitung zur Integration der Payments API, um eine sichere und effiziente Transaktionsverarbeitung zu gewährleisten.

Voraussetzungen

Bevor Sie Code schreiben, stellen Sie sicher, dass Sie Folgendes bereit haben:

  • Verifiziertes 4Geeks-Konto: Sie müssen Zugriff auf die 4Geeks Console haben.
  • Aktiver Zahlungsdienst: Stellen Sie sicher, dass das Payments-Modul in Ihren Kontoeinstellungen aktiviert ist.
  • API-Anmeldeinformationen: Sie benötigen Ihre Client ID und Ihr Client Secret (oder API-Schlüssel) aus dem Entwickler-Dashboard.
  • SSL-Zertifikat: Ihre Website muss Inhalte über HTTPS bereitstellen, um Transaktionsdaten sicher zu behandeln.

Schritt-für-Schritt-Anleitung

Befolgen Sie diese Schritte, um eine Standardzahlungsbelastung über die API zu verarbeiten.

Schritt 1: Ihre API-Anmeldeinformationen abrufen

Um mit der API zu kommunizieren, müssen Sie zunächst Ihre sicheren Anmeldeinformationen abrufen.

  1. Melden Sie sich bei der 4Geeks Console an.
  2. Navigieren Sie im Seitenmenü zu Settings > API Keys.
  3. Suchen Sie Ihre Client ID und Ihr Client Secret.

Tipp: Sie werden zwei Sätze von Schlüsseln sehen: „Test“ und „Live“. Verwenden Sie während der Entwicklung immer Testschlüssel, um Transaktionen zu simulieren, ohne echtes Geld zu bewegen. Wechseln Sie erst zu Live-Schlüsseln, wenn Sie bereit sind, zu starten.

Schritt 2: Ein Access Token generieren

Die 4Geeks API verwendet Bearer Token-Authentifizierung. Sie müssen Ihre Anmeldeinformationen gegen ein temporäres Zugriffstoken austauschen, bevor Sie Zahlungsanforderungen stellen können.

Endpunkt: POST /oauth/token

Request Body: 

    {
        "client_id": "IHRE_CLIENT_ID",
        "client_secret": "IHR_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }

Antwort: Die API gibt ein JSON-Objekt zurück, das ein access_token enthält. Sie verwenden dieses Token im Header Ihrer nachfolgenden Anfragen.

Schritt 3: Eine Zahlungsbelastung erstellen

Jetzt, da Sie authentifiziert sind, können Sie eine Transaktion einleiten. Diese Anfrage sendet die Zahlungsdetails zur Verarbeitung an 4Geeks.

Endpunkt: POST /v1/payments/

Headers:

  • Authorization: Bearer <IHR_ACCESS_TOKEN>
  • Content-Type: application/json

Body-Parameter:

  • amount: Die Gesamtkosten (z. B. 150.00).
  • currency: Der 3-stellige ISO-Code (z. B. USD, EUR).
  • description: Eine kurze Zusammenfassung des Kaufs.
  • return_url: Die URL, zu der Ihr Kunde nach dem Zahlungsvorgang weitergeleitet wird (wesentlich für 3D Secure-Abläufe).

Beispielanfrage:

{
  "amount": 150.00,
  "currency": "USD",
  "description": "Premium-Jahresabonnement",
  "return_url": "[https://ihre-website.de/checkout/success](https://ihre-website.de/checkout/success)"
}

Schritt 4: Die Antwort verarbeiten

Die API gibt den Status der Transaktion sofort zurück.

  • Erfolg: Wenn der Status succeeded oder approved ist, ist die Zahlung abgeschlossen. Sie sollten dem Benutzer eine Erfolgsmeldung anzeigen und Ihre Datenbank aktualisieren.
  • Aktion erforderlich: Wenn der Status action_required ist (häufig bei 3D Secure), enthält die Antwort eine redirect_url. Sie müssen den Kunden zu dieser URL weiterleiten, um die Bankverifizierung abzuschließen.

Häufige Anwendungsfälle

1. E-Commerce-Checkout

Ein Kunde legt Artikel in seinen Warenkorb und klickt auf „Kasse“. Ihr Backend berechnet die Gesamtsumme und ruft den Endpunkt /v1/payments/ auf. Bei einer erfolgreichen Antwort lösen Sie Ihr Inventarsystem aus (vielleicht verwaltet von 4Geeks Asset), um den Bestand zu reduzieren und eine Bestätigungs-E-Mail zu senden.

2. SaaS-Abonnementabrechnung

Für einen monatlichen Softwaredienst können Sie die Karte eines Kunden während seiner ersten Zahlung tokenisieren. Sie können dieses Token dann verwenden, um zukünftige Belastungen über die API zu automatisieren, ohne den Benutzer jeden Monat zur erneuten Eingabe seiner Daten aufzufordern. Dies lässt sich nahtlos in die Funktionen für wiederkehrende Abrechnungen von 4Geeks Payments integrieren.

Fehlerbehebung

Hier sind Lösungen für häufige Fehler, auf die Sie während der Integration stoßen könnten:

  • 401 Unauthorized Fehler:
  • Ursache: Ihr Bearer Token fehlt, ist falsch oder abgelaufen.

  • Lösung: Generieren Sie ein neues Token über den Endpunkt /oauth/token und stellen Sie sicher, dass es korrekt im Authorization-Header enthalten ist.

  • Transaktion abgelehnt (Allgemeiner Fehler):

  • Ursache: Der Kartenaussteller hat die Transaktion abgelehnt (z. B. unzureichende Deckung).

  • Lösung: Überprüfen Sie den error_code in der API-Antwort. Wenn Sie sich im Testmodus befinden, stellen Sie sicher, dass Sie die in der Dokumentation angegebenen gültigen Testkartennummern verwenden.

  • CORS-Fehler:

  • Ursache: Sie versuchen, API-Aufrufe direkt aus dem Browser (clientseitig) zu tätigen.
  • Lösung: Aus Sicherheitsgründen dürfen Sie Ihr Client Secret niemals im Frontend-Code preisgeben. Leiten Sie Zahlungsanforderungen immer über Ihren eigenen Backend-Server.

Fazit

Die Integration der 4Geeks Payments API gibt Ihnen die volle Kontrolle über Ihre Zahlungsabläufe und ermöglicht ein sicheres und individuelles Erlebnis für Ihre Benutzer. Wenn Sie diese Schritte befolgen, können Sie Kreditkarten sicher und effizient akzeptieren.

Für fortgeschrittenere Konfigurationen, wie das Speichern von Karten für die zukünftige Verwendung oder den Umgang mit Webhooks, besuchen Sie die 4Geeks Console oder erkunden Sie unsere Entwicklerdokumentation.

Zusätzliche Ressourcen