Zum Inhalt

Zahlungs-API

🤖 Erklären mit KI

Die Zahlungs-API ist ein Tool zur Zahlungsabwicklung, mit dem Unternehmen Online-Zahlungen sicher und effizient annehmen und verarbeiten können. Mit dieser API können Unternehmen Zahlungsabwicklungsfunktionen in ihre Websites, Anwendungen und andere Softwarelösungen integrieren.

Es werden alle gängigen Zahlungsmethoden unterstützt, einschließlich Kreditkarten, Debitkarten und digitale Geldbörsen. Darüber hinaus bietet sie Funktionen wie Echtzeit-Zahlungsabwicklung, automatische Währungsumrechnung und Betrugsprävention.

Alle Belastungsanfragen erfordern standardmäßig 3DS bei der Bank des Karteninhabers.

Eine Zahlungsanfrage erstellen

Endpunkt

POST /v1/payments/

Dieser Endpunkt erstellt eine einzelne sichere Abrechnungsseite basierend auf den folgenden Parametern. Bitte beachten Sie, dass Sie den Karteninhaber auf eine generierte Seite leiten müssen, auf der er die Daten zur Zahlungsmethode eingibt. Wir senden die Transaktionsantwort an die return_url.

Felder:

Parameter Beschreibung Typ Erforderlich
amount Gesamtbetrag der Belastung (Dezimalformat, z. B. 99.99) string ja
description Eine Beschreibung der Zahlung oder des Dienstes string ja
currency Ein gültiger Währungscode nach ISO-4217, zum Beispiel USD, CAD, CRC, EUR. string ja
items Name(n) der Produkte oder Dienstleistungen. Dies ist nur ein informatives Label. array ja
return_url Wir leiten nach Abschluss der Zahlung zu dieser URL weiter, wobei die id_payment als Query-Parameter angehängt wird, damit Sie den Transaktionsstatus abrufen können. string ja

Anfrage-Beispiel:

curl -X POST 'https://api.4geeks.io/v1/payments/' \
-u "sk_test_51O62xYzAbcDef123:" \
-H 'Content-Type: application/json' \
-d '{
    "amount": "500.00",
    "description": "Premium subscription payment",
    "currency": "USD",
    "items": ["Premium Plan - Monthly"],
    "return_url": "https://example.com/payment-result"
}'

import requests
from requests.auth import HTTPBasicAuth

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/v1/payments/',
    auth=HTTPBasicAuth(api_key, ""),
    json={
        "amount": "500.00",
        "description": "Premium subscription payment",
        "currency": "USD",
        "items": ["Premium Plan - Monthly"],
        "return_url": "https://example.com/payment-result"
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = Buffer.from(`${apiKey}:`).toString("base64");

fetch("https://api.4geeks.io/v1/payments/", {
    method: "POST",
    headers: {
        Authorization: `Basic ${credentials}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: "500.00",
        description: "Premium subscription payment",
        currency: "USD",
        items: ["Premium Plan - Monthly"],
        return_url: "https://example.com/payment-result",
    }),
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = btoa(`${apiKey}:`);

const headers = new HttpHeaders({
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
});

const payload = {
    amount: "500.00",
    description: "Premium subscription payment",
    currency: "USD",
    items: ["Premium Plan - Monthly"],
    return_url: "https://example.com/payment-result",
};

this.http
    .post("https://api.4geeks.io/v1/payments/", payload, { headers })
    .subscribe((data) => console.log(data));

Antwort (202 Accepted):

{
    "code": 202,
    "title": "Aktion erforderlich",
    "content": "Zeigen Sie die Checkout-Seite an, um die Zahlung abzuschließen.",
    "data": {
        "id_payment": "pay_1ABC123XYZ456",
        "redirect": "https://console.4geeks.io/checkout/?data=eyJyZXR1cm5fdXJsIjogImh0dHA6Ly9leGFtcGxlLmNvbS9wYXltZW50LXJlc3VsdCIsICJ0ZXN0IjogdHJ1ZSwgImhhc19jdXN0b21lciI6IGZhbHNlLCAiY29tcGFueV9lbWFpbCI6ICJzdXBwb3J0QDRnZWVrcy5pbyIsICJwcm9kdWN0IjogeyJ0b3RhbF9wcmljZSI6IDUwMC4wMCwgInByaWNlIjogNTAwLjAwLCAiY3VycmVuY3kiOiAiVVNEIiwgIm5hbWUiOiAiUHJlbWl1bSBzcWJzY3JpcHRpb24gcGF5bWVudCIsICJkZXNjcmlwdGlvbiI6IFsiUHJlbWl1bSBQbGFuIC0gTW9udGhseSJdfSwgInN0YXRlbWVudF9kZXNjcmlwdG9yIjogWyI0R0VFS1MiXSwgImNvbXBhbnlfbmFtZSI6ICI0R2Vla3MgUGF5bWVudHMifQ=="
    }
}

Eine Zahlung abrufen

Endpunkt

GET /v1/payments/{id}

Rufen Sie Details einer spezifischen Zahlungstransaktion anhand ihrer ID ab. Dieser Endpunkt gibt die vollständigen Transaktionsinformationen zurück, einschließlich Status, Betrag, Währung, Kundendetails und Informationen zur Zahlungsmethode.

Pfad-Parameter:

Parameter Beschreibung Typ Erforderlich
id Die eindeutige Zahlungs-ID (z. B. pay_1ABC123XYZ456) string ja

Query-Parameter:

Parameter Beschreibung Typ Erforderlich
test Nach Testmodus filtern (true/false) boolean nein

Anfrage-Beispiel:

curl -X GET 'https://api.4geeks.io/v1/payments/pay_1ABC123XYZ456' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Antwort (200 OK):

{
    "id": "pay_1ABC123XYZ456",
    "amount": "500.00",
    "currency": "USD",
    "description": "Premium subscription payment",
    "status": "completed",
    "items": ["Premium Plan - Monthly"],
    "customer_email": "customer@example.com",
    "return_url": "https://example.com/payment-result",
    "payment_method": "card",
    "card_last4": "4242",
    "card_brand": "visa",
    "created_at": "2025-12-04T10:30:00Z",
    "updated_at": "2025-12-04T10:35:00Z",
    "test": true
}

Fehlerantwort (404 Not Found):

{
    "code": 404,
    "title": "Zahlungen nicht gefunden",
    "content": "Bei der Suche sind Fehler aufgetreten, bitte überprüfen Sie die Daten.",
    "type": "danger"
}

Alle Zahlungen abrufen

Endpunkt

GET /v1/payments/internal

Rufen Sie eine paginierte Liste aller Zahlungen ab. Unterstützt Filter- und Sortieroptionen.

Query-Parameter:

Parameter Beschreibung Typ Erforderlich
status Nach Zahlungsstatus filtern (succeeded etc.) string nein
test Nach Testmodus filtern (true/false) boolean nein

Anfrage-Beispiel:

curl -X GET 'https://api.4geeks.io/v1/payments/?status=succeeded&test=false' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Antwort (200 OK):

[
    {
        "id": "7f277445-d4d0-47e2-bd6f-4664e4480778",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "5c35a9f5-cd2a-4bf5-a0e2-d946eedeefeb",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-11-04T14:33:25.690012Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    },
    {
        "id": "e7d9a0ea-58fb-45a0-8005-e2c314bcf3d1",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "9928c043-e480-4b77-aa31-88de9ae52e7c",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-09-17T20:58:39.797400Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    }
]

Fehlerbehandlung

Die API gibt Standard-HTTP-Statuscodes zurück, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen. Nachfolgend sind häufige Fehler aufgeführt, die spezifisch für die Zahlungs-API sind:

Statuscode Fehlertyp Beschreibung
400 Bad Request Erforderliche Felder fehlen oder ungültiges Format für Betrag/Währung.
401 Unauthorized Fehlende oder ungültige API-Key-Authentifizierung.
402 Payment Required Zahlungsmethode abgelehnt oder unzureichende Deckung.
404 Not Found Zahlungs-ID existiert nicht.
409 Conflict Doppelte Zahlungsanfrage (Idempotenzprüfung).
500 Server Error Unerwarteter Serverfehler während der Zahlungsabwicklung.

Beispiel: Unauthorized (401)

{
    "detail": "Ungültiges API-Key-Format."
}

Beispiel: Zahlung fehlgeschlagen (402)

{
    "error": {
        "code": 402,
        "type": "payment_failed",
        "message": "Karte abgelehnt. Bitte versuchen Sie eine andere Zahlungsmethode.",
        "decline_reason": "unzureichende_deckung"
    }
}

Häufige Probleme & Fehlerbehebung

Problem: 401 Unauthorized

  • Überprüfen Sie, ob Ihr API-Key ist korrekt und nicht vor kurzem rotiert wurde
  • Stellen Sie sicher, dass der Basic Auth Header den abschließenden Doppelpunkt (:) enthält
  • Überprüfen Sie, ob der Schlüsseltyp (Test/Live) zu Ihrer Umgebung passt